API – Nested Objects – Tripleseat Support

The Tripleseat Open API supports creating, updating, and deleting nested (associated) objects through their parent object endpoints. Nested objects are managed using structured JSON payloads within the parent object's request body.

How Nested Object Updates Work

When updating nested records via a parent object (e.g., Contacts, Accounts, Events, Bookings), the following rules apply:

If id is provided → the existing nested record is updated.
If id is omitted → a new nested record is created.
If _destroy is set to true → the nested record is deleted.

Supported Nested Objects

The following nested object types are supported across various parent endpoints:

Email Addresses
Phone Numbers
Addresses
Websites
Custom Field Values
Selected Lead Sources
Lead Booking Events

Email Addresses

Used within Contacts and Accounts.

Fields

Field	Required	Description
`id`	No	Provide to update an existing email record
`address`	Yes (on create)	Email address (RFC 5322 format)
`_destroy`	No	Set to `true` to delete the record

Phone Numbers

Used within Contacts and Accounts.

Fields

Field	Description
`id`	Provide to update existing record
`number`	Phone number (without extension)
`extension`	Phone extension
`phone_number_type`	One of: Main, Work, Home, Mobile, Fax, Pager, Skype
`_destroy`	Set to `true` to delete

Addresses

Used within Contacts, Accounts, and Lead offsite addresses.

Fields

Field	Description
`id`	Provide to update existing record
`address1`	First address line
`address2`	Second address line
`city`	City or municipality
`state`	State or province (abbreviated for US/Canada)
`zip_code`	Postal code
`country`	Country
`address_type`	Main, Work, Home, Other, Delivery, Offsite
`_destroy`	Set to `true` to delete

Websites

Used within Contacts and Accounts.

Fields

Field	Description
`id`	Provide to update existing record
`url`	Valid URI
`_destroy`	Set to `true` to delete

Custom Field Values

Supported on:

Events
Bookings
Leads
Contacts
Accounts

Fields

Field	Required	Description
`id`	No	Provide to update an existing custom field value
`custom_field_id`	Yes	ID of the custom field
`value`	Yes	Value for the custom field
`_destroy`	No	Set to `true` to delete

Creating Custom Fields (POST)

{
  "custom_field_values": [
    {
      "custom_field_id": 1234,
      "value": "Example value"
    }
  ]
}

Updating Custom Fields (PUT/PATCH)

{
  "custom_field_values": [
    {
      "id": 1234567,
      "custom_field_id": 1234,
      "value": "Updated value"
    }
  ]
}

Selected Lead Sources (Bookings & Leads)

Used to associate lead sources to Bookings and Leads.

Field	Description
`id`	Provide to update existing association
`lead_source_id`	ID of lead source
`lead_source_other`	Optional custom description
`_destroy`	Set to `true` to remove association

Booking-Lead Events (/Leads Only)

Allows multiple event date/time entries on booking-type leads.

Field	Description
`id`	Provide to update existing entry
`event_date`	Date of event (YYYY-MM-DD)
`start_time`	Event start time
`end_time`	Event end time
`guest_count`	Number of guests
`event_description`	Description for this event instance
`_destroy`	Set to `true` to delete entry

Important Notes

Nested updates must be sent within the parent object's request body.
All nested objects follow the Association Tracking pattern.
Boolean _destroy must be true to delete records.
Some nested associations are only available on specific parent objects.