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:

1. Authorization
2. 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:

1. Add your Merge API key (from your dashboard) to the request headers
2. 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:

1. A model field that contains the object data to write to the third-party platform
2. 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 the personal_email and work_email fields as strings
• For Merge ATS, Candidate emails are located in the email_addresses field, which is an array of objects with two fields (value and email_address_type)

1
{
2
  "model": {
3
    "first_name": "Jane",
4
    "last_name": "Doe",
5
    "work_email": "jane@merge.dev",
6
    "personal_email": "jane@gmail.com"
7
  }
8
}

1
{
2
  "model": {
3
    "first_name": "Jane",
4
    "last_name": "Doe",
5
    "email_addresses": [
6
      {
7
        "value": "jane@merge.dev",
8
        "email_address_type": "WORK",
9
      },
10
      {
11
        "value": "jane@gmail.com",
12
        "email_address_type": "PERSONAL",
13
      }
14
    ]
15
  }
16
} 

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

1
{
2
  "model": {
3
    "first_name": "Jane",
4
    "last_name": "Doe",
5
    "email_addresses": [
6
      {
7
        "value": "jane@merge.dev",
8
        "email_address_type": "WORK",
9
      },
10
      {
11
        "value": "jane@gmail.com",
12
        "email_address_type": "PERSONAL",
13
      }
14
    ],
15
  }
16
  "remote_user_id": "example_user_id"
17
}

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:

1. A model field containing the fields of the newly created common model, if successfully created
2. A warnings field containing messaging on issues with the request that did not cause it to fail
3. An errors field containing messaging on issues with the request that caused it to fail
4. 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:

1. The Merge ID of the newly created model will be generated and contained in the id field
2. 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.