Overview

Templates

Conditional Fields

Example

First /meta Request

Second /meta Request

Templates and Conditional Fields

Use /meta to determine conditional fields based on your user’s input in another field

Overview

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_id

Typically, 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:

  1. The first /meta request is to get the initial POST request schema including any templates and a flag indicating the existence of conditional fields.
  2. After your user has selected a template, you will make a second /meta request 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 Intern means college is required
  • Selecting FTE means college is 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:

  1. You will need to make a first GET request to /candidates/meta/post to be aware of the existence of any template choices.
  2. Once your user selects a template, you will make a second GET request to /candidates/meta/post to 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.

Warning

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).

Example request_schema featuring Application templates (nested in Candidate)

JSON
{
"request_schema": {
"type": "object",
"properties": {
"model": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The candidate's first name."
},
"last_name": {
"type": "string",
"description": "The candidate's last name."
},
"applications": { // Available fields for nested model
"type": "array",
"items": {
"type": "object",
"properties": {
"applied_at": {
"type": "string",
"description": "When the application was submitted."
},
"source": {
"type": "string",
"description": "Source of the application."
},
"remote_template_id": {
"type": "string",
"enum": ["INTERN", "FTE"],
"enum_information": [
{
"value": "INTERN",
"description": "Intern"
},
{
"value": "FTE",
"description": "Full-Time Employee"
}
]
},
"anyOf": [
{
"remote_template_id": {
"const": "INTERN"
},
"linked_account_params": {
"type": "object",
"properties": {
"college": {
"type": "string",
"description": "The college that the candidate currently attends."
}
},
"required": ["college"]
}
},
{
"remote_template_id": {
"const": "FTE"
},
"linked_account_params": null
}
]
},
"required": ["remote_template_id"]
},
"description": "Array of ats.Application objects on ats.Candidate"
}
},
"required": ["first_name", "last_name"]
}
},
"required": ["model"]
},
"has_conditional_fields": true
}

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

Important Note

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.

Example request_schema featuring Application's conditional fields

JSON
{
"request_schema": {
"type": "object",
"properties": {
"model": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The candidate's first name."
},
"last_name": {
"type": "string",
"description": "The candidate's last name."
},
"applications": { // Available fields for nested model
"type": "array",
"items": {
"type": "object",
"properties": {
"applied_at": {
"type": "string",
"description": "When the application was submitted."
},
"source": {
"type": "string",
"description": "Source of the application."
},
// Shows the active remote_template_id
"remote_template_id": {
"const": "INTERN"
},
"linked_account_params": {
"type": "object",
"properties": {
"college": {
"type": "string",
"description": "The college that the candidate currently attends."
}
},
"required": ["college"]
}
},
"required": ["linked_account_params"]
},
"description": "Array of ats.Application objects on ats.Candidate"
}
},
"required": ["first_name", "last_name"]
}
},
"required": ["model"]
},
"has_conditional_fields": false
}

In accordance with your second /meta response, your final valid POST request might look like the following:

Example POST request body

JSON
{
"model": {
"first_name": "Jane",
"last_name": "Doe",
"applications": [
{
"applied_at": "2021-10-15T00:00:00Z",
"source": "Campus recruiting event",
"remote_template_id": "INTERN",
"linked_account_params": {
"college": "University of California Los Angeles",
},
}
]
}
}