> This page is for Unified. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Templates and Conditional Fields > How to handle dynamic form fields where available options depend on the value of another field, using /meta endpoint templates. --- ## 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](https://developers.greenhouse.io/harvest.html#post-create-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). > **Info** > > Refer to our guide to [Programmatic Writes with /meta](../programmatic-writes-with-meta/introduction) for an introduction to using `/meta`. 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`. > **Info** > > Refer to our guide to [Programmatic Nested Writes with /meta](./nested) 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) ```json {29-42,67,77} { "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": { "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 } ``` #### `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. > > > **Info** > > > > `anyOf` is included in `request_schema` as a JSON Schema convention. > > > > To learn more about `anyOf`, refer to the [JSON Schema specification](../programmatic-writes-with-meta/introduction#request_schema). #### `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: ```bash 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](../writes/nested)) — you would **prepend the nested Common Model name** to the query parameter of the second GET request. This GET request may look like: ```bash GET .../candidates/meta/post?application_remote_template_id=INTERN ``` > **Info** > > **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 ```json {29-42,54} { "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": { "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 } ``` #### `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.) > **Info** > > Refer to our guide to [Programmatic Writes with `/meta`](../programmatic-writes-with-meta/introduction) 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 ```json {9-12} { "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", }, } ] } } ```