All docs

The data model in the API and for AI agents

Create objects and fields, read and write records, run duplicate checks and merges from the REST API or an AI agent.

Updated . 5 min read.

Everything on these pages can be done from code or from an AI agent. Access tokens need the ability crm:read (to read) or crm:write (to change). The matching contacts: abilities work too. Role and object permissions apply to a token exactly as they do to the person who made it. Custom objects need the Team plan or above; contacts, companies, deals and tasks work on the plan that has them.

REST API

The endpoints live under /api/v1/crm:

What Endpoints
Objects GET/POST /crm/objects, GET/PATCH/DELETE /crm/objects/{object}
Fields /crm/objects/{object}/fields, with archive and restore
Relations /crm/objects/{object}/relations
Views /crm/objects/{object}/views
Records /crm/objects/{object}/records, plus batch (up to 60 at a time), upsert on a unique field and restore
Deleted records /crm/objects/{object}/trash: list, restore several, delete one or several permanently (queued)
Notes and tasks /crm/objects/{object}/records/{record}/notes and /tasks
Import and export /crm/objects/{object}/imports and /exports
Duplicates and merges GET /crm/objects/{object}/duplicates, POST /crm/objects/{object}/merges and .../merges/{merge}/undo
Permissions GET/PUT /crm/objects/{object}/permissions
The whole data model as a file GET /crm/schema, PUT /crm/schema (compare with dry_run, import, prune), GET /crm/schema/applies/{id}; see Export, import and share
Dashboards /crm/dashboards (list, create, change, delete), .../widgets, PUT .../layout (the grid), GET .../data (the numbers, narrowed by date_range, date_from and date_to), .../versions (with .../versions/{version}/restore), POST .../duplicate, PUT/DELETE .../favorite, POST /crm/dashboards/preview and GET /crm/dashboard-widgets/{widget}/data for a chart limited to one record; see Dashboards and charts
Record page layout GET/PUT/DELETE /crm/objects/{object}/layout, GET .../layout/versions and POST .../layout/versions/{version}/restore

Contacts, companies, deals and tasks are objects like any other here (contact, account, deal, task). Their built-in fields are fields of the object: a write goes through the same rules, plan limits and events as their own endpoints, a delete is queued, and a contact's email and phone can be filtered as whole values (is, is_not, in, empty). Their own endpoints and all the mobile and integration contracts stay as they are.

A list takes a filter tree, a sort, a search text, a saved view and a cursor, and can load related records in the same call. Each field says whether a list can be ordered by it (sortable); a sort by a field that cannot be (a contact's email and phone) is refused with a 422 on sorts.0.field. Every endpoint is described in the API reference.

Changes to records announce crm_record.created, crm_record.updated, crm_record.deleted, crm_record.restored and crm_record.merged to webhooks and automations. Only the keys of the fields that changed are sent, never their values.

AI agents

The same set of tools works for every object. The object's key is an argument, so there is no tool per object.

To Tools
Learn the model list_crm_objects, get_crm_object
Change the model create_crm_object, update_crm_object, create_crm_field, update_crm_field, archive_crm_field, create_crm_relation
Work with records list_crm_records, get_crm_record, create_crm_record, update_crm_record, delete_crm_record, bulk_crm_records, search_crm_records
Deleted records list_crm_trash, restore_crm_trash, erase_crm_trash
Duplicates and merges list_crm_merges, merge_crm_records, undo_crm_merge
Views list_crm_views, create_crm_view, update_crm_view, delete_crm_view; list_crm_calendar reads the records of a calendar window
Notes and tasks add_crm_record_note, create_crm_record_task
Files upload_crm_file, then set the Files field of a record to the returned ids with create_crm_record or update_crm_record
The whole data model get_crm_schema, plan_crm_schema (compare, changes nothing), apply_crm_schema, get_crm_schema_apply
Record page layout get_crm_object_layout, update_crm_object_layout (also resets with reset)
Permissions and row rules get_crm_object_permissions, update_crm_object_permissions (roles, record rules and hidden or read-only fields; owner and administrators only)
Dashboards list_crm_dashboards, get_crm_dashboard (with the numbers), create_crm_dashboard, update_crm_dashboard, delete_crm_dashboard, add_crm_dashboard_widget, update_crm_dashboard_widget, remove_crm_dashboard_widget, arrange_crm_dashboard, duplicate_crm_dashboard, list_crm_dashboard_versions, restore_crm_dashboard_version, preview_crm_chart
Favorites list_crm_favorites, star_crm_favorite, reorder_crm_favorites, unstar_crm_favorite

To find records that have notes, tasks or files, filter list_crm_records on attached_notes, attached_tasks or attached_files with not_empty (or empty for the ones that have none).

The workspace search tool also finds records of your own objects. Deleting and bulk changes are treated as high-risk actions, so a token that asks for confirmation holds them for your approval.