Programmatic Writes with /meta
/meta to ensure you are including the correct model fields when making POST requests to Merge across varying linked accountsIntroducing /meta
Merge’s Common Models have most fields you need, but there are advanced use cases where the fields available for POST requests to Merge change based on the third-party platform or user.
Merge’s /meta endpoint helps you account for these use cases by dynamically fetching modelfield names, types, and other metadata used for making writes to a given integration or Linked Account.
Instead of building customized logic for every integration, /meta allows you to:
- Dynamically prompt users for required / optional and standard / non-standard fields
- Build once to create or update data for all third-party platforms
- Programmatically account for Linked Account differences and customizations
- Validate POST requests for all required information
GET Request to /meta
All Merge POST endpoints have an associated /meta GET endpoint.
For example, to get the integration- or account-specific schema for a successful POST request to /candidates, make a GET request to /candidates/meta/post first.
Account Token
To identify the specific integration and Linked Account, pass the account_token for the Linked Account you are looking to write data to in the header of your API request.
Response from /meta
The response from /meta will return requirements for writing data to a specific integration or Linked Account.
The response will contain three components:
request_schemastatus- booleans that make it easier to work with
request_schemaand build programmatic flows
request_schema
The request_schema object is the bulk of the /meta response and contains details about the model fields for the POST request specific to the integration or Linked Account.
Specifically, model in the /meta response will have the following properties:
model Property | Description |
| Common Model fields | The Common Model fields listed here are writable to the integration or Linked Account. |
integration_params | Integration-specific writable model fields not part of Merge’s Common Model. |
linked_account_params | Linked Account-specific writable model fields not part of Merge’s Common Model. |
remote_template_id | In some cases, this enum input from your user determines whether there are additional field inputs required from your user. Learn more in our guide to Programmatic Writes with /meta for Fields Conditional on User Input. |
Common Model Fields
Given the natural differences in third-party platforms, the request_schema is useful for determining writability and optionality of each Common Model field for each integration.
See an example of a basic request_schema below:
Example - Request Schema
See an example of a basic request_schema:
Example - Request Body
In accordance with the response from /meta above, the POST request you would form might have a body like this:
Non-Common Model Fields
In addition to Common Model fields, some integrations and Linked Accounts may have varying writable Non-Common Model fields (fields not part of Merge’s standardized data model).
These fields are contained in integration_params and linked_account_params.
Integration-Specific Fields (integration_params)
Non-Common Model fields that are specific to certain third-party platforms will be contained in integration_params.
Example - Request Schema
Let’s say an ATS platform requires a stage field for newly created Candidates, even though this field is not included in our Common Model.
As a result, the Candidate’s stage must be added to model in the body of POST requests to Merge for this specific third-party platform.
The request_schema for this integration may look like:
Example - Request Body
In accordance with the response from /meta above, the POST request you would form might have a body like this:
A Note on Integration-Specific Fields and Linked Account-Specific Enum Values
If you are writing to an integration with an integration-specific Non-Common Model field with consistent enum choices across all Linked Accounts (like Archived and Active in the above example), then it may be unnecessary to use /meta to dynamically form POST requests since you can anticipate the choices for the field.
However, if that integration-specific field has enum choices that vary by Linked Account, then it would be necessary to use /meta to dynamically surface the enum choices to your user.
Example:
Instead of stage having fixed enum options of Archived and Active, let’s say that different Linked Accounts for the same integration have varying enum choices for the stage field (which is not part of Merge’s Candidate Common Model).
For example, Linked Account A could have Archived and Active stages and Linked Account B could have Unprocessed and Processed stages (illustrated below).
When passing the different Linked Account tokens in your GET request to /meta, the integration_params object in each /meta response would look like the following:
Linked Account A
Linked Account B
Linked Account-Specific Fields (linked_account_params)
Non-Common Model fields that are specific to Linked Accounts will be contained within the linked_account_params object within the request_schema.
Example - Request Schema
An ATS integration can allow a Linked Account to specify that a hackerrank_score is required when creating a Candidate.
Since hackerrank_score isn’t a field in Merge’s Candidate Common Model and it’s writability depends on the Linked Account’s configuration, you would use /meta to determine whether this input is required from your user.
Here is an example /meta response denoting the hackerrank_score field as required for the given Linked Account:
Example - Request Body
In accordance with the response from /meta above, the POST request you would form might have a body like this:
status
The status object within /meta can tell you if an integration is down or if a Linked Account is not properly connected, either of which will block POST requests.
status has three properties:
| Property | Type | Options | Description |
integration_status | Enum | OK, DOWN | Operational status of integration. |
linked_account_status | Enum | COMPLETE, RELINK_NEEDED | Connection status of Linked Account. |
can_make_request | boolean | true, false | Returns true if integration_status is OK and linked_account_status is COMPLETE. This property is included for convenience. |
Helper Variables
The /meta response also includes a few helper variables for convenience:
| Property | Type | Options | Description |
has_required_linked_account_params | boolean | true, false | Returns true if there are required Linked Account-specific fields contained within the /meta response. |
has_conditional_fields | boolean | true, false | Returns true if there are POST request fields conditional on your user’s input in another field. |