Templates and Conditional Fields
/metato determine conditional fields based on your user’s input in another field
When writing data to third-party platforms, you will sometimes be required to select a template when creating a new instance of a Common Model.
These templates are typically user-defined and Linked Account-specific (but not always).
/meta endpoint will offer clarity in its
request_schema as to which templates are available for selection (see example further below).
Typically, these templates are given a unique ID and might be referred to by varying names (e.g.,
application_type_id, etc.) depending on third-party platform.
Merge refers to these template IDs by the standardized name
Depending on template selection, there may arise conditional fields that require inputs.
These conditional fields may be outside of Merge’s Common Model.
This situation — where conditional possibilites are present (pending template selection) — will be flagged by the
has_conditional_fields boolean flag in
In this situation, we suggest you make two GET requests to
- The first
/metarequest is to get the initial POST request schema including any templates and a flag indicating the existence of conditional fields.
- After your user has selected a template, you will make a second
/metarequest with the template selection as a parameter to fetch the schema of the conditional fields.
After those two GET requests to
/meta, you should have the full schema required to construct a valid POST request.
Suppose an ATS platform requires users to specify a template when applying a candidate to a job.
One Linked Account belonging to your end user happens to contain user-defined (and, therefore, Linked Account-specific)
FTE application templates.
Intern application template requires the candidate’s
college information, which isn’t part of Merge’s
Application Common Model.
Depending on your user’s template selection:
Furthermore, let’s assume you want to do a single POST request with an
Application nested inside a
You might set up your product to interact with our API as follows:
- You will need to make a first GET request to
/candidates/meta/postto be aware of the existence of any template choices.
- Once your user selects a template, you will make a second GET request to
/candidates/meta/postto fetch the full requirements — including any conditional fields — for a valid POST request to Merge.
Step 1 — First
You will do your first GET request to
/candidates/meta/post to fetch the
request_schema and determine if there are any
Candidate or nested Common Model templates (like
Application in this example) and conditional fields to be accounted for.
The response to this request might look like this example:
/candidates/meta/post declares that selecting a
remote_template_id is a required input to nest an
Application within a newly created
As a result, you should make a second GET request to
/candidates/meta/post with the selection of your
remote_template_id as a query parameter to determine full requirements for a valid POST request to create a new
Candidate with a nested
Instead of parsing
anyOf, we highly recommend making a second request to
/meta with your user’s selection of
remote_template_id to re-use any programmatic logic you may already have in place to handle basic
anyOf may look trivial to parse in the example above, this is an illustrative example and may include much more complex branching in production, which can result in errors.
request_schema has several helper variables to help you programmatically form valid POST requests.
One of those variables is the
When this boolean flag is
true, there are POST request fields conditional on your user’s selection of
remote_template_id for the
Candidate or any nested Common Models (like
Application in this example).
Step 2 - Second
In your second GET request to
/candidates/meta/post, pass your user’s
remote_template_id selection in the request as a query parameter like this:
In the illustrative two-step example in this guide, since the
remote_template_id selection of
INTERN pertains to an
Application nested in a
Candidate, you would prepend the nested Common Model name to the query parameter like in the “Templates with Nested Writes” box above.
The response from this second GET request to
/candidates/meta/post would provide the information needed to construct a valid POST request for creating a new
Candidate (with a nested
Application) for the given Linked Account.
Since you submitted a valid
remote_template_id as part of your second
/meta request, you will see the active template in your
With an active template, this
request_schema now shows an updated
linked_account_params object specifying that
college is required for the nested
(This is in
linked_account_params because this is a user-defined template and, therefore, a Linked Account-specific field.)
has_conditional_fields is now false, signifying that all conditional possibilities in
Candidate and any nested Common Models (like
Application in this example) have been resolved.
In accordance with your second
/meta response, your final valid POST request might look like the following: