Overview

Writing Data with Relations

Writing Nested Data

Related and Nested Writes

Write data to third-party platforms with relations to existing and new Common Model instances

Overview

Common Models sometimes have relationships with other Common Models.

For example:

  • Merge HRIS Employees can have related Employments
  • Merge ATS Candidates can have related Applications
  • 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.

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

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
{
  "model": {
    "first_name": "Gil",
    "last_name": "Feig",
    "employments": [
      { // Employment Common Model
        "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
{
  "model": {
    "first_name": "Gil",
    "last_name": "Feig",
    "company": "Columbia Dining App.",
    "title": "Software Engineer",
    "applications": [
      { // Application Common Model
        "remote_id": "98796",
        "job": "52bf9b5e-0beb-4f6f-8a72-cd4dca7ca633",
        "source": "Campus recruiting event"
      }
    ],
    "phone_numbers": [],
    "email_addresses": [],
    "urls": [],
    "tags": [],
    "attachments": [],
  }
}
Previous
Writes
Next Up
Programmatic Writes with /meta