Overview

Request Schema for Nested Common Models

Programmatic Nested Writes with /meta

Use /meta to create related Common Model instances (through nesting) with standardized or integration / Linked Account-specific fields

Overview

In an earlier guide to Writing Nested Data, we introduced the concept of writing new entities nested inside another entity in a single POST request to Merge, thereby establishing a relation.

Nested Writes are supported for only a few Common Model pairs. Refer to our guide to Writing Nested Data for support details.

Just like how /meta can be used to programmatically determine writable fields for a Common Model, /meta can also be used to determine writable fields for a nested Common Model.


Request Schema for Nested Common Models

In your /meta response, the request_schema object will have similar properties whether it is for the parent or nested Common Model:

  • Common Model fields
  • integration_params specifying integration-specific fields
  • linked_account_params specifying Linked Account-specific fields

Example - Request Schema

Candidates can accept a nested Application in its applications field.

A GET request to /candidates/meta/post will show supported fields for this nesting in its response:

Example request_schema for Candidate with nested Application

JSON
{
"request_schema": {
"type": "object",
"properties": {
"model": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The candidate's first name."
},
"last_name": {
"type": "string",
"description": "The candidate's last name."
},
"email_addresses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
},
"email_address_type": {
"type": "string",
}
},
"required": ["value"]
},
"description": "Array of email_addresses objects on ats.Candidate"
},
"applications": { // Available fields for nested model
"type": "array",
"items": {
"type": "object",
"properties": {
"applied_at": {
"type": "string",
"description": "When the application was submitted."
},
"source": {
"type": "string",
"description": "Source of the application."
},
"integration_params": null, // Integration-specific fields for Applications would be included here
"linked_account_params": null // Linked Account-specific fields for Applications would be included here
}
},
"description": "Array of ats.Application objects on ats.Candidate"
},
"integration_params": null,
"linked_account_params": null
},
"required": ["first_name", "last_name"]
}
}
}
}

Example - Request Body

In accordance with the response from /meta above, the POST request you would form might have a body like this:

Example POST request body

JSON
{
"model": {
"first_name": "Jane",
"last_name": "Doe",
"email_addresses": [
{
"value": "jane@merge.dev",
"email_address_type": "WORK",
},
{
"value": "jane@gmail.com",
"email_address_type": "PERSONAL",
}
],
"applications": [
{
"applied_at": "2021-10-15T00:00:00Z",
"source": "Campus recruiting event"
}
]
}
}