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

Supported Relations

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.

Example body of POST request to /employees

1 {
2   "model": {
3     "first_name": "Gil",
4     "last_name": "Feig",
5     "team": "249c9faa-3045-4a31-953b-8f22d3613301" // Merge ID
6   }
7 }

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

1 {
2   "model": {
3     "file_name": "Candidate Resume",
4     "file_url": "http://alturl.com/p749b",
5     "candidate": "2872ba14-4084-492b-be96-e5eee6fc33ef", // Merge ID
6     "attachment_type": "RESUME"
7   }
8 }

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.

Example body of POST request to /employees with nested employment

1 {
2   "model": {
3     "first_name": "Gil",
4     "last_name": "Feig",
5     "employments": [
6       {
7         "job_title": "Software Engineer",
8         "pay_rate": "80000.00",
9         "pay_period": "YEAR",
10         "pay_currency": "USD",
11         "employment_type": "FULL_TIME"
12       }
13     ]
14   }
15 }

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

1 {
2   "model": {
3     "first_name": "Gil",
4     "last_name": "Feig",
5     "company": "Columbia Dining App.",
6     "title": "Software Engineer",
7     "applications": [
8       {
9         "remote_id": "98796",
10         "job": "52bf9b5e-0beb-4f6f-8a72-cd4dca7ca633",
11         "source": "Campus recruiting event"
12       }
13     ],
14     "phone_numbers": [],
15     "email_addresses": [],
16     "urls": [],
17     "tags": [],
18     "attachments": []
19   }
20 }