← All action domains

Custom objects

14 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

New record

custom_objects.create_recordwriteconfirm

Create a custom-object record with validated field values and optional contact linkage. Queues custom_record_created for enabled workflows, which may send messages or incur provider charges according to their configured steps.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
type_idstring (uuid)requiredThe object type to create a record of.
valuesmap of string → objectrequiredThe record's field values, keyed by field key (see the type's fields from custom_objects.list_types). Example: {"address": "12 Oak St", "price": 950000}. A Team member (kind user) field takes a current team member's email address or user id.
primary_contact_idstring (uuid)optionalContact to file this record under. Shows the record on that contact's screen.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.create_record \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "values": {}
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_create_record at https://app.chirply.io/api/mcp, same bearer token, same input.

New object type

custom_objects.create_typewriteadmin only

Create a custom object type — a new kind of record this account can store (e.g. "Property"). Takes the singular and plural names plus the typed fields records of this kind carry. The type immediately appears in the app's navigation and its records become creatable everywhere. Owners and admins only: a type is account SCHEMA, not a record — it changes the sidebar and the shape of everyone's data.

Parameters

FieldTypeRequiredDescription
name_singularstringrequiredWhat one record is called, e.g. "Property". Shown on buttons and headings.
name_pluralstringrequiredWhat many records are called, e.g. "Properties". Becomes the navigation label.
iconstringoptionalOptional icon name for the navigation row (a lucide icon name like "home").
keystringoptionalURL slug for the type (lowercase letters, digits, dashes; starts with a letter). Omit to derive it from the plural name. Permanent once created.
fieldsobject[]optionalThe fields records of this type carry, in display order. The first text field becomes each record's display name. Default: []
fields[].keystringoptionalStorage key for the field's values (snake_case, starts with a letter). Omit to derive it from the label. Keys are permanent once records exist.
fields[].labelstringrequiredThe field's name as people see it, e.g. "Purchase price".
fields[].kind"text" | "textarea" | "number" | "currency" | "date" | "select" | … 7 moreoptionalWhat the field holds: text, textarea (long text), number, currency (major-unit amount; options contains one ISO currency code, USD by default), date (YYYY-MM-DD), select (one choice from `options`), multiselect (array of choices from `options`), checkbox (yes/no), url, phone, email, contact_link (free-form reference to a contact), or user (a Team member — one current account member, written as their email or user id and stored as the user id). Default: "text"
fields[].optionsstring[]optionalFor select/multiselect: a nonempty list of choices. For currency: one uppercase ISO currency code such as USD or EUR (USD when omitted); amounts are major units, not cents. Default: []
fields[].requiredbooleanoptionalWhen true, a record cannot be created without a value for this field. Default: false
fields[].descriptionstringoptionalOptional help text for the field, up to 1,000 characters — what belongs in it and the format to follow, e.g. "One link per line, as Label | URL". Shown under the field on the app's record form and returned by custom_objects.list_types and custom_objects.get_record, so people and AI assistants writing records can follow it.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.create_type \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name_singular": "Example",
    "name_plural": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_create_type at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete a record

custom_objects.delete_recordwriteconfirm

Permanently delete one custom-object record and all of its stored values. This cannot be undone.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe record to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.delete_record \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_delete_record at https://app.chirply.io/api/mcp, same bearer token, same input.

Record columns

custom_objects.get_column_layoutread

Read which columns you see on one custom object type's record list and in what order, plus every column that type could show (the record name, each of its fields, the linked contact, and dates). Personal to you — it does not affect what teammates see. Returns the type's defaults when you have never changed them.

Parameters

FieldTypeRequiredDescription
type_idstring (uuid)requiredThe object type whose list columns to read (from custom_objects.list_types).

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.get_column_layout \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_get_column_layout at https://app.chirply.io/api/mcp, same bearer token, same input.

Object field layout

custom_objects.get_layoutread

Read the team-wide layout of one custom object type's fields: its named sections in order with the field keys in each, the fields at the top that aren't in a section, hidden fields, whether empty fields are tucked away — and its case types: which dropdown sets each record's type (type_field) and which fields belong only to some types (field_types; a field not listed is on every type). Changes nothing.

Parameters

FieldTypeRequiredDescription
type_idstring (uuid)requiredThe object type (from custom_objects.list_types).

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.get_layout \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_get_layout at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a record

custom_objects.get_recordread

Fetch one custom-object record by id, with all of its stored field values, its primary contact, `people` (everyone on the record: primary first, then each related contact with their role) and `fields` — the type's field definitions in display order (key, label, kind, choices, required, and the optional `description` help text that states what belongs in each field and its format).

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe record's id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.get_record \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_get_record at https://app.chirply.io/api/mcp, same bearer token, same input.

List records

custom_objects.list_recordsread

List the records of one custom object type, most recently updated first. Optionally filter to the records a specific contact is on — as the primary contact, as a related contact (any role), or picked in a "Link to a contact" field — to the records where a Team member field names someone ("properties where I'm the agent": member_field + member), or text-search across each record's stored values.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
type_idstring (uuid)requiredThe object type whose records to list (from custom_objects.list_types).
contact_idstring (uuid)optionalOnly records this contact is on: as the primary contact, as a related contact (related_contacts.add), or picked in one of the type's "Link to a contact" fields. Up to 100 linked records.
member_fieldstringoptionalKey of one of this type's Team member fields (kind "user"). Requires `member`.
memberstringoptionalWho `member_field` must name: "me" (the signed-in person; not available to API keys), a team member's user id, or their email address.
querystringoptionalText to match in a record's stored values (case-insensitive). Values of 2,000+ characters, such as raw import dumps, are not searched.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.list_records \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_list_records at https://app.chirply.io/api/mcp, same bearer token, same input.

Custom objects

custom_objects.list_typesread

List this account's custom object types — the user-defined record types beyond contacts, companies and deals (e.g. Properties, Pets, Policies) — including each type's field definitions: key, label, kind, choices, required, and `description`, the field's optional help text. Read a field's description before writing to it — it often states the format the value must follow (e.g. "One link per line, as Label | URL"). Each field also carries its layout: `section_id`, `hidden`, `is_type_field` (this dropdown's choices are the type's case types) and `show_for` (the case types it belongs to; empty = every type) — custom_objects.get_layout explains them.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.list_types \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool custom_objects_list_types at https://app.chirply.io/api/mcp, same bearer token, same input.

Reset record columns

custom_objects.reset_column_layoutwrite

Forget your saved column choices for one custom object type's record list so it goes back to that type's default columns (the record name, its first few fields, the linked contact, and the first-added date). Personal to you, and affects only which columns are displayed — no record data is changed or deleted.

Parameters

FieldTypeRequiredDescription
type_idstring (uuid)requiredThe object type whose list columns to reset (from custom_objects.list_types).

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.reset_column_layout \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_reset_column_layout at https://app.chirply.io/api/mcp, same bearer token, same input.

Save record columns

custom_objects.set_column_layoutwrite

Choose which columns you see on one custom object type's record list and in what order — the array order IS the left-to-right order, and any column you leave out is hidden. Personal to you; teammates' lists are unaffected. Unknown keys are dropped and the record's Name column is always kept (it is the link into each record), so the list can never be left unusable. Call custom_objects.get_column_layout for the valid keys.

Parameters

FieldTypeRequiredDescription
type_idstring (uuid)requiredThe object type whose list columns to save (from custom_objects.list_types).
columnsstring[]requiredOrdered column keys, e.g. ['label','field:price','primary_contact']. A type's fields use the 'field:<field key>' form.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.set_column_layout \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "columns": [
      "example"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_set_column_layout at https://app.chirply.io/api/mcp, same bearer token, same input.

Arrange object fields

custom_objects.set_layoutwriteadmin only

Change the team-wide layout of one custom object type's fields — the same changes as its builder page in Settings → Custom objects: create, rename, reorder or delete named sections, place and order fields, hide or show fields on record pages and forms, turn "hide empty fields" on or off, and set up case types — choose which dropdown's choices are the types (type_field) and which types each field belongs to (field_types). A record then shows only its type's fields plus the shared ones. Applies to everyone in the account at once. Nothing stored is changed: deleting a section moves its fields to the top, a hidden or other-type field keeps its values, and stopping types (type_field null) shows every field again. Owners and admins only.

Parameters

FieldTypeRequiredDescription
type_idstring (uuid)requiredThe object type (from custom_objects.list_types).
sectionsobject[]optionalThe COMPLETE list of sections, in display order (up to 50). A section left out is deleted — its fields move to the top of the record; no field or value is deleted. Omit to leave sections as they are.
sections[].idstring (uuid)optionalAn existing section's id (from the get_layout result) to keep or rename it. Omit to create a new section.
sections[].namestringrequiredThe section's heading on record pages, e.g. "Property Info". Up to 80 characters; unique within the layout.
sections[].fieldsstring[]optionalField keys to place in this section, in display order. Fields you don't place anywhere keep their current section.
unsectionedstring[]optionalField keys for the group at the top of the record (not in any section), in display order.
hidestring[]optionalField keys to hide from record pages and forms. Their values are kept and still work in lists, filters, merge fields, automations and the API.
showstring[]optionalField keys to show on record pages and forms again.
hide_emptybooleanoptionalWhen true, record pages tuck fields with no value behind "Show empty fields" (required fields always show).
type_fieldstring (or null)optionalKey of the dropdown (select) field whose choices are this object's types, e.g. "case_type" with choices Tax Deed and Mortgage Foreclosure. null stops splitting records into types (each field remembers its types). To create the dropdown first, use custom_objects.update_type with add_fields. Omit to leave as is.
field_typesmap of string → arrayoptionalWhich types each field belongs to: field key → list of type names (choices of the type field). An empty list, or every type, means the field is shared by all types. Fields not listed keep what they have. Needs a type field.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.set_layout \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_set_layout at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit field

custom_objects.update_fieldwriteadmin only

Change one existing field on a custom object type — its label, description (help text), dropdown choices or required flag, and its kind while no record holds a value in it. The field is identified by its key, which never changes, so every value records already store stays attached. Stored values are never rewritten: a record holding a dropdown choice you remove keeps that value (the app shows it as "no longer a choice") until someone picks a current one, and making a field required leaves records without a value as they are — the app's form asks for one the next time each is saved. The result counts the records each of those affects. Changing the kind of a field that records already hold values in is refused (add a new field instead). Owners and admins only, the same as creating or editing a type.

Parameters

FieldTypeRequiredDescription
type_idstring (uuid)requiredThe object type the field belongs to (from custom_objects.list_types).
keystringrequiredThe field to edit, by its key (the `key` custom_objects.list_types returns for it, e.g. "purchase_price"). Identifies the field only — keys never change.
labelstringoptionalNew name for the field as people see it. Omit to keep the current one.
descriptionstring (or null)optionalNew help text for the field, up to 1,000 characters — e.g. "One link per line, as Label | URL". Shown under the field on the record form and returned by custom_objects.list_types and get_record. null or "" removes it; omit to keep the current one.
optionsstring[]optionalFor currency: one uppercase ISO currency code (USD by default). For select/multiselect: the COMPLETE new list of choices, in display order — include every choice to keep. A choice left out is removed for new values; records already holding it keep it until changed. Omit to keep the current choices.
requiredbooleanoptionalWhether a record needs a value in this field. Turning it on does not change existing records; the app's form asks for a value the next time one without it is saved. Omit to keep the current setting.
kind"text" | "textarea" | "number" | "currency" | "date" | "select" | … 7 moreoptionalNew kind for the field (text, textarea, number, currency, date, select, multiselect, checkbox, url, phone, email, contact_link or user). Allowed only while no record of this type holds a value in the field — otherwise refused, since stored values would no longer fit. Changing to select requires `options`. Omit to keep the current kind.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.update_field \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "key": "example"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_update_field at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit a record

custom_objects.update_recordwriteconfirm

Update supplied fields or contact linkage on a custom record, validating its field definitions. Actual changes queue custom_record_updated for enabled workflows, which may send messages or incur provider charges according to their configured steps. Unchanged values do not emit events.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe record to edit.
valuesmap of string → objectoptionalField values to change, keyed by field key. A null or empty value clears an optional field; omitted keys are left alone.
primary_contact_idstring (uuid) (or null)optionalContact to link the record to, or null to unlink it.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.update_record \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_update_record at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit object type

custom_objects.update_typewriteadmin only

Rename a custom object type or change its icon, and optionally add new fields to it (each may carry a description). Existing fields and records are untouched; the URL name (key) never changes. To change an existing field — its label, description, choices or required flag — use custom_objects.update_field. Owners and admins only, same as creating one.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe object type to edit.
name_singularstringoptionalWhat one record is called, e.g. "Property". Shown on buttons and headings.
name_pluralstringoptionalWhat many records are called, e.g. "Properties". Becomes the navigation label.
iconstring (or null)optionalOptional icon name for the navigation row (a lucide icon name like "home").
add_fieldsobject[]optionalNew fields to append to the type, in order after the existing ones. Default: []
add_fields[].keystringoptionalStorage key for the field's values (snake_case, starts with a letter). Omit to derive it from the label. Keys are permanent once records exist.
add_fields[].labelstringrequiredThe field's name as people see it, e.g. "Purchase price".
add_fields[].kind"text" | "textarea" | "number" | "currency" | "date" | "select" | … 7 moreoptionalWhat the field holds: text, textarea (long text), number, currency (major-unit amount; options contains one ISO currency code, USD by default), date (YYYY-MM-DD), select (one choice from `options`), multiselect (array of choices from `options`), checkbox (yes/no), url, phone, email, contact_link (free-form reference to a contact), or user (a Team member — one current account member, written as their email or user id and stored as the user id). Default: "text"
add_fields[].optionsstring[]optionalFor select/multiselect: a nonempty list of choices. For currency: one uppercase ISO currency code such as USD or EUR (USD when omitted); amounts are major units, not cents. Default: []
add_fields[].requiredbooleanoptionalWhen true, a record cannot be created without a value for this field. Default: false
add_fields[].descriptionstringoptionalOptional help text for the field, up to 1,000 characters — what belongs in it and the format to follow, e.g. "One link per line, as Label | URL". Shown under the field on the app's record form and returned by custom_objects.list_types and custom_objects.get_record, so people and AI assistants writing records can follow it.

Example

curl -X POST https://app.chirply.io/api/v1/actions/custom_objects.update_type \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool custom_objects_update_type at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=custom_objects — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.