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

# Related and Nested Writes

> How to create records that reference existing objects (related writes) or create parent and child objects in a single request (nested writes).

---

## Overview

Common Models sometimes have relationships with other Common Models.

For example:

* Merge HRIS `Employees` can have related `Employments`
* Merge ATS `Applications` can have related `Candidates`
* Merge ATS `Candidates` can have related `Attachments`

Our POST endpoints allow you to:

* Create relationships to existing entities through references to Merge ID's
* Create new related entities through nesting

> **Warning**
>
> You cannot create references to the Merge IDs of existing Common Model instances at the same time as a Nested Write.

---

## Writing Data with Relations to Existing Data

When sending POST requests to Merge, related Common Model instances can be referenced by their Merge ID.

> **Info**
>
> All Common Model fields that accept references to other Common Model instances by their Merge ID are supported in POST requests.
>
> Refer to our [API reference](/merge-unified/hris/overview) to see what references are supported.

### HRIS Example

When creating an `Employee` using our HRIS API, a relationship between an `Employee` and an existing `Team` can be created by adding the Merge ID of the relevant `Team` to the new `Employee's team` field.

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

```json {5}
{
  "model": {
    "first_name": "Gil",
    "last_name": "Feig",
    "team": "249c9faa-3045-4a31-953b-8f22d3613301" // Merge ID
  }
}
```

### ATS Example

When creating an `Attachment` using our ATS API, a relationship between an `Attachment` and an existing `Candidate` is created by adding the Merge ID of the relevant `Candidate` to the new `Attachment's candidate` field.

#### Example body of POST request to /attachments

```json {5}
{
  "model": {
    "file_name": "Candidate Resume",
    "file_url": "http://alturl.com/p749b",
    "candidate": "2872ba14-4084-492b-be96-e5eee6fc33ef", // Merge ID
    "attachment_type": "RESUME"
  }
}
```

---

## Writing Nested Data

Our POST endpoints allow you to create related Common Models in-line (also known as a **Nested Write**) if the related entity hasn't been created yet.

> **Info**
>
> Nested Writes are supported for only the following use cases at this time:
>
> * `Employee` — single nested `Employment` in `Employee's employments` field
> * `Candidate` — single nested `Application` in `Candidate's applications` field
> * `Candidate` — multiple nested `Attachments` in `Candidate's attachments` field

### HRIS Example

When creating an `Employee` using our HRIS API, to create a new related `Employment` within a new `Employee`, you would pass the details of the `Employment` in an object within the new `Employee's employments` field.

#### Example body of POST request to /employees with nested employment

```json {5-13}
{
  "model": {
    "first_name": "Gil",
    "last_name": "Feig",
    "employments": [
      {
        "job_title": "Software Engineer",
        "pay_rate": "80000.00",
        "pay_period": "YEAR",
        "pay_currency": "USD",
        "employment_type": "FULL_TIME"
      }
    ]
  }
}
```

### ATS Example

When creating a `Candidate` using our ATS API, to create a new related `Application` within a new `Candidate`, you would pass the details of the `Application` in an object within the new `Candidate's applications` field.

#### Example body of POST request to /candidates with nested applications

```json {7-13}
{
  "model": {
    "first_name": "Gil",
    "last_name": "Feig",
    "company": "Columbia Dining App.",
    "title": "Software Engineer",
    "applications": [
      {
        "remote_id": "98796",
        "job": "52bf9b5e-0beb-4f6f-8a72-cd4dca7ca633",
        "source": "Campus recruiting event"
      }
    ],
    "phone_numbers": [],
    "email_addresses": [],
    "urls": [],
    "tags": [],
    "attachments": []
  }
}
```