Fresh 2026

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

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.

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

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

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

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.

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

{
  "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": []
  }
}