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

# Writes

> How to create and update records in third-party platforms via POST and PATCH requests to Merge's Unified API.

---

## 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](/merge-unified/hris/overview) 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](https://app.merge.dev)) to the request headers
2. Add your user's `account_token` to identify the third-party platform and linked account to update

> **Info**
>
> Refer to our [Authentication guide](/basics/authentication) for more details on using `account_token`.

### 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`)

> **Info**
>
> Refer to our [API reference](/merge-unified/hris/overview) to learn more about specific model parameters.

#### Example body of POST request to \`/employees\`

```json {5-6}
{
  "model": {
    "first_name": "Jane",
    "last_name": "Doe",
    "work_email": "jane@merge.dev",
    "personal_email": "jane@gmail.com"
  }
}
```

#### Example body of POST request to \`/candidates\`

```json {5-14}
{
  "model": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email_addresses": [
      {
        "value": "jane@merge.dev",
        "email_address_type": "WORK",
      },
      {
        "value": "jane@gmail.com",
        "email_address_type": "PERSONAL",
      }
    ]
  }
} 
```

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

> **Info**
>
> To check if this parameter is required for a given ATS integration, use the [Linked Accounts endpoint](/merge-unified/platform-and-account-metadata/linked-accounts).

#### Example body of POST request to \`/candidates\`

```json {16}
{
  "model": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email_addresses": [
      {
        "value": "jane@merge.dev",
        "email_address_type": "WORK",
      },
      {
        "value": "jane@gmail.com",
        "email_address_type": "PERSONAL",
      }
    ],
  }
  "remote_user_id": "example_user_id"
}
```

---

## 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

> **Info**
>
> Learn more about **Nested Writes** in our guide to [Writing Nested Data](/merge-unified/writing-data/writes/nested)

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

> **Info**
>
> Learn more about **warnings and errors** in our guide to [Troubleshooting Writes](/merge-unified/writing-data/troubleshooting-writes/troubleshooting-tools)