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

Writing Data with Relations to Existing Data

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

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.

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.

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.

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.

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.

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
}