Merge Writes: Programmatic Nested Writes with /meta

Overview

Request Schema for Nested Common Models

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.

Refer to our guide to Programmatic Writes with /meta for an introduction to using /meta.

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": "[email protected]",
        "email_address_type": "WORK",
      },
      {
        "value": "[email protected]",
        "email_address_type": "PERSONAL",
      }
    ],
    "applications": [
      {
        "applied_at": "2021-10-15T00:00:00Z",
        "source": "Campus recruiting event"
      }
    ]
  }
}