Programmatic Nested Writes with /meta

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

Refer to our documentation of request_schema for more information.

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

1 {
2     "request_schema": {
3         "type": "object",
4         "properties": {
5             "model": {
6                 "type": "object",
7                 "properties": {
8                     "first_name": {
9                         "type": "string",
10                         "description": "The candidate's first name."
11                     },
12                     "last_name": {
13                         "type": "string",
14                         "description": "The candidate's last name."
15                     },
16                     "email_addresses": {
17                         "type": "array",
18                         "items": {
19                             "type": "object",
20                             "properties": {
21                                 "value": {
22                                     "type": "string",
23                                 },
24                                 "email_address_type": {
25                                     "type": "string",
26                                 }
27                             },
28                             "required": ["value"]
29                         },
30                         "description": "Array of email_addresses objects on ats.Candidate"
31                     },
32                     "applications": {
33                         "type": "array",
34                         "items": {
35                             "type": "object",
36                             "properties": {
37                                 "applied_at": {
38                                     "type": "string",
39                                     "description": "When the application was submitted."
40                                 },
41                                 "source": {
42                                     "type": "string",
43                                     "description": "Source of the application."
44                                 },
45                                 "integration_params": null,
46                                 "linked_account_params": null
47                             }
48                         },
49                         "description": "Array of ats.Application objects on ats.Candidate"
50                     },
51                     "integration_params": null,
52                     "linked_account_params": null
53                 },
54                 "required": ["first_name", "last_name"]
55             }
56         }
57     }
58 }

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

1 {
2   "model": {
3     "first_name": "Jane",
4     "last_name": "Doe",
5     "email_addresses": [
6       {
7         "value": "jane@merge.dev",
8         "email_address_type": "WORK",
9       },
10       {
11         "value": "jane@gmail.com",
12         "email_address_type": "PERSONAL",
13       }
14     ],
15     "applications": [
16       {
17         "applied_at": "2021-10-15T00:00:00Z",
18         "source": "Campus recruiting event"
19       }
20     ]
21   }
22 }