Templates and Conditional Fields
/meta to determine conditional fields based on your user’s input in another fieldOverview
Templates
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).
The associated /meta endpoint will offer clarity in its request_schema as to which templates are available for selection (see example further below).
remote_template_idTypically, these templates are given a unique ID and might be referred to by varying names (e.g., candidate_type_id, application_type_id, etc.) depending on third-party platform.
Merge refers to these template IDs by the standardized name remote_template_id.
Conditional Fields
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 request_schema.
In this situation, we suggest you make two GET requests to /meta:
- 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.
Example
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) Intern and FTE application templates.
The 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:
- Selecting
Internmeanscollegeis required - Selecting
FTEmeanscollegeis unavailable
Furthermore, let’s assume you want to do a single POST request with an Application nested inside a Candidate.
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 /meta Request
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:
remote_template_id
This first request_schema from /candidates/meta/post declares that selecting a remote_template_id is a required input to nest an Application within a newly created Candidate.
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 Application.
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 /meta schemas.
While 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.
has_conditional_fields
request_schema has several helper variables to help you programmatically form valid POST requests.
One of those variables is the has_conditional_fields flag.
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 /meta Request
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:
GET https://api.merge.dev/api/ats/v1/candidates/meta/post?remote_template_id=INTERN
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.
remote_template_id
Since you submitted a valid remote_template_id as part of your second /meta request, you will see the active template in your request_schema.
linked_account_params
With an active template, this request_schema now shows an updated linked_account_params object specifying that college is required for the nested Application.
(This is in linked_account_params because this is a user-defined template and, therefore, a Linked Account-specific field.)
has_conditional_fields
Note that 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: