Writing dataProgrammatic writes with /meta

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

For example, when creating a Greenhouse job via POST request directly to their API, the JSON body requires a template_job_id parameter indicating an existing job and associated settings used to generate the new job.

The associated /meta endpoint will offer clarity in its request_schema as to which templates are available for selection (see example further below).

Refer to our guide to Programmatic Writes with /meta for an introduction to using /meta.

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.

Refer to our guide to Programmatic Nested Writes with /meta for an introduction to using /meta for nested writes.

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:

Example request_schema featuring Application templates (nested in Candidate)
1{
2    "request_schema": {
3        "type": "object",
4        "properties": {
5            "model": {
6                "type": "object",
7                "properties": {
8                    "first_name": {
9                        "type": "string",
10                        "description": "The candidate's first name."
11                    },
12                    "last_name": {
13                        "type": "string",
14                        "description": "The candidate's last name."
15                    },
16                    "applications": {
17                        "type": "array",
18                        "items": {
19                            "type": "object",
20                            "properties": {
21                                "applied_at": {
22                                    "type": "string",
23                                    "description": "When the application was submitted."
24                                },
25                                "source": {
26                                    "type": "string",
27                                    "description": "Source of the application."
28                                },
29                                "remote_template_id": {
30                                    "type": "string",
31                                    "enum": ["INTERN", "FTE"],
32                                    "enum_information": [
33                                        {
34                                            "value": "INTERN",
35                                            "description": "Intern"
36                                        },
37                                        {
38                                            "value": "FTE",
39                                            "description": "Full-Time Employee"
40                                        }
41                                    ]
42                                },
43                                "anyOf": [
44                                    {
45                                        "remote_template_id": {
46                                            "const": "INTERN"
47                                        },
48                                        "linked_account_params": {
49                                            "type": "object",
50                                            "properties": {
51                                                "college": {
52                                                    "type": "string",
53                                                    "description": "The college that the candidate currently attends."
54                                                }
55                                            },
56                                            "required": ["college"]
57                                        }
58                                    },
59                                    {
60                                        "remote_template_id": {
61                                            "const": "FTE"
62                                        },
63                                        "linked_account_params": null
64                                    }
65                                ]
66                            },
67                            "required": ["remote_template_id"]
68                        },
69                        "description": "Array of ats.Application objects on ats.Candidate"
70                    }
71                },
72                "required": ["first_name", "last_name"]
73            }
74        },
75        "required": ["model"]
76    },
77    "has_conditional_fields": true
78}

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.

anyOf is included in request_schema as a JSON Schema convention.

To learn more about anyOf, refer to the JSON Schema specification.

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/candidates/meta/post/?remote_template_id=INTERN

Templates with Nested Writes

In the event that remote_template_id pertains to a template selection made for a nested Common Model — such as a template for an Application nested in a Candidate (as part of a Nested Write) — you would prepend the nested Common Model name to the query parameter of the second GET request.

This GET request may look like:

$GET .../candidates/meta/post?application_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.

Example request_schema featuring Application's conditional fields
1{
2    "request_schema": {
3        "type": "object",
4        "properties": {
5            "model": {
6                "type": "object",
7                "properties": {
8                    "first_name": {
9                        "type": "string",
10                        "description": "The candidate's first name."
11                    },
12                    "last_name": {
13                        "type": "string",
14                        "description": "The candidate's last name."
15                    },
16                    "applications": {
17                        "type": "array",
18                        "items": {
19                            "type": "object",
20                            "properties": {
21                                "applied_at": {
22                                    "type": "string",
23                                    "description": "When the application was submitted."
24                                },
25                                "source": {
26                                    "type": "string",
27                                    "description": "Source of the application."
28                                },
29                                // Shows the active remote_template_id
30                                "remote_template_id": {
31                                  "const": "INTERN"
32                                },
33                                "linked_account_params": {
34                                    "type": "object",
35                                    "properties": {
36                                        "college": {
37                                            "type": "string",
38                                            "description": "The college that the candidate currently attends." 
39                                        }
40                                    },
41                                    "required": ["college"]
42                                }
43                            },
44                            "required": ["linked_account_params"]
45                        },
46                        "description": "Array of ats.Application objects on ats.Candidate"
47                    }
48                },
49                "required": ["first_name", "last_name"]
50            }
51        },
52        "required": ["model"]
53    },
54    "has_conditional_fields": false
55}

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

Refer to our guide to Programmatic Writes with /meta for an introduction to Linked Account-specific fields and using linked_account_params.

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 Body

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

Example POST request body
1{
2  "model": {
3    "first_name": "Jane",
4    "last_name": "Doe",
5    "applications": [
6      {
7        "applied_at": "2021-10-15T00:00:00Z",
8        "source": "Campus recruiting event",
9        "remote_template_id": "INTERN",
10        "linked_account_params": {
11            "college": "University of California Los Angeles", 
12        },
13      }
14    ]
15  }
16}