Writes
Introducing Writes
Merge’s Unified API allows you to write data to third-party platforms.
You can create new entities and update existing entities in your end users’ Linked Accounts.
Limitations
Merge supports POST requests and PATCH requests based on availability from third-party platforms.
Refer to our API Reference to confirm which platforms and data models support POST and PATCH requests. We are constantly increasing our support across third-party platforms.
POST Requests to Merge
A POST request to Merge’s API consists of two parts:
- Authorization
- Request Body
Authorization
As with any Merge API interaction, POST requests to Merge require authentication parameters to (1) authorize users to create or update data and (2) tell Merge which third-party platform to write to.
To authorize your request:
- Add your Merge API key (from your dashboard) to the request headers
- Add your user’s
account_token
to identify the third-party platform and linked account to update
Request Body
Your POST request body will include the following:
- A
model
field that contains the object data to write to the third-party platform - For ATS integrations: a
remote_user_id
parameter to confirm that you have permission to POST data to that integration
Model
The model
body parameter contains the field values of the Common Model instance you are looking to create.
These fields expect different data types depending on the category, third-party platform, and Common Model.
For example:
- For Merge HRIS,
Employee
emails are located in thepersonal_email
andwork_email
fields as strings - For Merge ATS,
Candidate
emails are located in theemail_addresses
field, which is an array of objects with two fields (value
andemail_address_type
)
HRIS Example
ATS Example
Remote User ID (ATS only)
Some ATS integrations need to verify that your user has permission to create candidates and link them to open jobs.
For these platforms, add Merge’s ID for your end user (specifically, the id
field in the response from a GET request to Merge’s /users
endpoint) in the remote_user_id
field in the Request Body (as in the example).
ATS Example
Response to POST Request
After making a request to Merge’s POST endpoints, the response will be a JSON object with up to four properties:
- A
model
field containing the fields of the newly created common model, if successfully created - A
warnings
field containing messaging on issues with the request that did not cause it to fail - An
errors
field containing messaging on issues with the request that caused it to fail - If Debug Mode is enabled, a
logs
field containing the IDs of logs related to outbound requests made to the third-party platform during the request
Model
If the POST request is successful, the model
field will contain a full JSON representation of the newly created Common Model instance.
The fields and associated values within the model
object will largely correspond to what was sent in the POST request body, with the following exceptions:
- The Merge ID of the newly created model will be generated and contained in the
id
field - Any Nested Writes will be resolved, and the Merge IDs of the newly created related Common Model instances will be returned in the response within their respective fields
Warnings and Errors
The warnings
field contains details on issues that don’t stop the request from being successful.
The errors
field contains details on issues that cause the request to fail.