Everything here uses the contacts:read and contacts:write token abilities. Companies and deals
need the Team plan or above; below it they answer 402. Another workspace's records answer 404.
Every list is paged with an opaque cursor: send meta.next_cursor back as cursor.
Contact timeline, notes and call log
| Method | Path | What it does |
|---|---|---|
| GET | /contacts/{contact}/timeline |
Newest-first activity across all products. include_counts=1 adds counts per source. |
| GET, POST | /contacts/{contact}/notes |
List (pinned first) or add a note. format=html is cleaned before it is stored. |
| PATCH, DELETE | /contacts/{contact}/notes/{note} |
Edit (the earlier text is kept) or delete (queued). |
| PUT | /contacts/{contact}/notes/{note}/pin |
pinned: true or false. |
| GET | /contacts/{contact}/notes/{note}/revisions |
Earlier versions. |
| GET, POST | /contacts/{contact}/activities |
List or log a call, meeting or email with a summary. |
| PATCH, DELETE | /contacts/{contact}/activities/{activity} |
Edit or delete (queued). |
| POST | /contacts/{contact}/follow-up |
A task days from now at 09:00 workspace time. |
Tasks
GET /tasks takes view (mine, today, overdue, all, done) and contact; meta.counts
holds the badge counts. POST /tasks creates one; PATCH /tasks/{task} changes it;
POST /tasks/{task}/complete and /reopen change its status; DELETE is queued. A task due now
sends the assignee an email and a push notification once, and publishes a task.due event.
Lifecycle stages
GET /lifecycle-stages lists the stages (a workspace that has not changed them yet sees the
defaults Lead, Qualified, Customer and Lost). POST adds one, PATCH /lifecycle-stages/{stage}
renames it, PUT /lifecycle-stages/order reorders, DELETE is queued and takes move_to.
Set a contact's stage with PUT /contacts/{contact}/lifecycle-stage and {"stage": "qualified"}
(null clears it). Each move publishes contact.stage_changed once.
Companies
GET, POST /companies; GET, PATCH, DELETE /companies/{company}. Link people with
POST /companies/{company}/contacts (contact_id, optional primary and role) and unlink with
DELETE /companies/{company}/contacts/{contact}. GET /companies/{company}/contacts?suggestions=1
adds people who share the company's email domain; they are hints and are never linked for you.
GET /companies/{company}/revenue returns paid orders per currency and Feedback revenue accounts,
each with its source, and never one combined total. POST /companies/{company}/merge takes
duplicate_id and is queued; the merge is recorded like every merge of the data model and can be
undone for 14 days (see Duplicates and merges).
Pipelines and deals
GET, POST /pipelines; PATCH, DELETE /pipelines/{pipeline}; stages under
/pipelines/{pipeline}/stages. The default pipeline is created with the first deal or the first
visit to the board, not by a read. GET, POST /deals; GET, PATCH, DELETE /deals/{deal};
POST /deals/{deal}/move with stage_id (and lost_reason for a lost stage).
A deal has its own currency (three letters) and amount_minor in minor units. GET /deals and
GET /deals/totals group totals by currency in meta.totals; amounts in different currencies are
never added together.
Addresses, consent and email
POST /contacts/{contact}/identifiers/{identifier}/verificationsends the person a one-time confirmation for a second email address (a link) or phone number (a text message). It answers202; the message is queued.422says why nothing was sent: already verified, an address that bounced, a number whose owner withdrew consent for text messages, no text messaging set up, sample data, or asked too often. Until it is confirmed,verification.statusispendingorunverified, and an unverified second identifier never attaches a submission or payment to the contact (verification.identifies).GETandPOST /contacts/{contact}/consentstake achannelofmarketing_email(the default),sms,phone,whatsapporpostal. The top level of the answer is the marketing-email state;channelslists all five.GET /contact-email-templates,POST,PATCHandDELETE /contact-email-templates/{id}manage the reusable messages;GETandPUT /contact-email-signaturemanage your own signature. Bodies are HTML, cleaned when saved, and a merge tag that does not exist ({{ nickname }}) answers422. Deleting answers202and hides the template at once. All of this is part of the Scale plan.POST /contacts/{contact}/emailalso takestemplate,format(plainorhtml) andsignature.PUT /crm/capture-ownertakes one ofform,funnel,survey,bio_pageorbooking_pageto give that surface its own owners.- Notes, activities, a company's people and the consent history are paged with
cursorandper_page; the answer carriesmeta.next_cursor.
Sorting and segment rules
GET /contacts and GET /contacts/export take sort: last_seen_desc (the default),
last_seen_asc, created_desc, created_asc, name, tags_desc, tags_asc (by number of tags),
owner_asc, owner_desc (by the owner's name), or field:{key}:asc|desc for a custom field. A
custom field sorts by its own type (text, number or date); an unknown field key falls back to the
default order. Contacts without a value sort as the smallest.
A segment's filters tree may also hold tag (hasTag, hasNoTag with a tag id), list
(isOnList, isNotOnList with a list id) and owner (equals, doesNotEqual with a member user
id, or isSet, isNotSet) conditions. They work in contact lists, previews and segment filters;
assigning a segment that uses them to a survey answers 422.
Events
contact.created, contact.updated, contact.merged, contact.merge_undone, contact.deleted,
contact.consent_changed, contact.stage_changed, contact.owner_changed, contact.tag_added,
contact.tag_removed, contact.list_added, contact.list_removed and task.due are published
once per change. Deal facts are deal.created, deal.stage_changed, deal.won and deal.lost; company facts are company.created, company.updated, company.merged (the surviving company, with the id of the one folded into it) and company.deleted.
Payloads carry ids and field names, never email addresses, phone numbers or attribute values.
Tag and list membership events carry the tag or list id and name (tag_id, tag, list_id,
list) and are published once per contact whose membership really changed; tagging a contact that
already has the tag, or removing one that does not, publishes nothing. When a member leaves the
workspace, every contact they owned publishes contact.owner_changed (to_user_id is null,
the actor is the system).
The tags and lists themselves publish workspace-level events whose subject is the tag or list, not
a contact: contact_tag.created, contact_tag.renamed (with from and to),
contact_tag.deleted, contact_list.created, contact_list.renamed (with from and to) and
contact_list.deleted. A deletion is announced when the queued job finishes and carries
memberships_removed; it does not publish one event per contact. Changing only a tag's colour or
a list's description publishes nothing.
A CSV import does not publish one contact.created (or contact.updated, contact.tag_added,
contact.list_added, contact.consent_changed) per row, so importing a file starts no workflow per person. When a run
finishes it publishes a single contacts.imported with the import id, its status and the counts of
rows created, updated, skipped and failed. A dry run publishes nothing.
Retries
Every POST that creates a record here accepts an Idempotency-Key header: contacts, companies,
deals, tasks, pipelines and stages, lifecycle stages, notes, activities, follow-ups, identifiers,
custom fields, tags, lists, saved views, and the bulk, import and export requests. Repeating a
request with the same key and the same body returns the first response (marked with
Idempotent-Replayed: true) and creates nothing; the same key with a different body answers 409.
Keys are scoped to your workspace and kept for seven days.
Data model: objects, fields, relations, views and records
A second set of endpoints works on the CRM's data model, whatever the object: contacts, companies, deals
and tasks, and the custom objects a workspace defines (projects, properties, invoices). It uses the
crm:read and crm:write token abilities; contacts:read and contacts:write also grant them. Custom
objects, their fields, views and records are part of the Team plan and above (402 below it); the
standard objects can be listed and read on the plans that have them. Another workspace's objects and
records answer 404. Every create takes an Idempotency-Key; every delete is queued and answers 202.
| Method | Path | What it does |
|---|---|---|
| GET | /crm/field-types |
What each field type can do: filter operators, sorting, totals. |
| GET, POST | /crm/objects |
List the objects, or create a custom object. |
| GET, PATCH, DELETE | /crm/objects/{object} |
Show, change (or switch off with is_active) or delete a custom object. {object} is its key, such as projects, or contact, account, deal, task. |
| GET, POST | /crm/objects/{object}/fields |
List or add fields. A field keeps its key and type. |
| GET, PATCH, DELETE | /crm/objects/{object}/fields/{field} |
Show, change, or delete an archived field with its values. |
| PUT | /crm/objects/{object}/fields/{field}/options |
Replace the options of a select. |
| POST | /crm/objects/{object}/fields/{field}/archive, /restore |
Switch a field off or on; its values stay. |
| PUT | /crm/objects/{object}/fields/order |
Put the fields in order. |
| GET, POST | /crm/objects/{object}/relations |
List relations, or relate this object to another: a field appears on each side. |
| PATCH, DELETE | /crm/objects/{object}/relations/{relation} |
Change what deleting the "one" side does, or delete the relation. |
| GET, POST | /crm/objects/{object}/views |
List the views you can open, or save a table, board or calendar view (type: calendar with settings.calendar.date_field). |
| GET, PATCH, DELETE | /crm/objects/{object}/views/{view} |
Show, change or delete a view. |
| GET, PUT, DELETE | /crm/objects/{object}/layout |
The layout of the record page (tabs, sections, widgets); save a new version, or go back to the built-in one. |
| GET | /crm/objects/{object}/layout/versions |
The last 20 versions of the layout. |
| POST | /crm/objects/{object}/layout/versions/{version}/restore |
Make an earlier version the layout again, as a new version. |
| GET, POST | /crm/dashboards |
The dashboards you can open (shared with the workspace, and your private ones), or create one, optionally with widgets. Limited per plan. |
| GET | /crm/dashboards/catalog |
Widget types and sizes, measures, date buckets and presets, series colours and the grid. |
| POST | /crm/dashboards/preview |
Run the settings of a widget that is not saved. |
| GET, PATCH, DELETE | /crm/dashboards/{dashboard} |
Open, change (base_version gets 409 when it moved on) or delete (queued) a dashboard. |
| PUT | /crm/dashboards/{dashboard}/layout |
Move and resize widgets on the 12-column grid in one save. |
| POST, PATCH, DELETE | /crm/dashboards/{dashboard}/widgets, .../widgets/{widget} |
Add, change or remove a widget. Errors name the setting, such as config.group_by. |
| GET | /crm/dashboards/{dashboard}/data, .../widgets/{widget}/data |
The numbers, worked out for you from the records, fields and rows you may read. date_range, date_from and date_to, or date_last, narrow them. Money is one series per currency. |
| GET | /crm/dashboard-widgets/{widget}/data |
A widget limited to the records linked to one record (object, record, scope_field). |
| PUT, DELETE | /crm/dashboards/{dashboard}/favorite |
Star or unstar a dashboard for yourself. |
| GET, POST | /crm/dashboards/{dashboard}/versions, .../versions/{version}/restore |
The last 20 versions, and putting one back. |
| GET, PUT | /crm/schema |
The whole data model as one versioned document, and the way back in (compare with dry_run, import, prune). See The data model as a document. |
| GET | /crm/schema/applies/{apply} |
Where an import that runs in the background stands. |
| GET, POST | /crm/favorites |
Your favorites in the workspace, in your order, or star an object, a view or a record. |
| PUT | /crm/favorites/order |
Put your favorites in order. |
| DELETE | /crm/favorites/{favorite} |
Remove a favorite of yours. |
| GET | /crm/objects/{object}/calendar |
The records in a window of days (from, to, at most 100 days) by date_field and optional end_field, or a calendar view. Ordered by start, at most 500; meta.truncated says the window held more. A datetime field is cut into the days of timezone. |
| GET, POST | /crm/objects/{object}/records |
List records, or create one. |
| GET, PATCH, DELETE | /crm/objects/{object}/records/{record} |
Show, change or delete a record. |
| POST | /crm/objects/{object}/records/{record}/restore |
Bring a deleted record back. |
| GET | /crm/objects/{object}/trash |
The deleted records of a custom object, most recently deleted first (search, cursor, per_page). They keep their unique values until erased. Needs the right to delete the object's records. |
| POST | /crm/objects/{object}/trash/restore |
Bring up to 100 deleted records back (ids); all or none. |
| DELETE | /crm/objects/{object}/trash/{record} |
Erase one deleted record for good; queued. Frees its unique values. |
| DELETE | /crm/objects/{object}/trash |
Erase up to 100 deleted records (ids) or the whole trash (all: true) for good; queued. |
| POST, PATCH, DELETE | /crm/objects/{object}/records/batch |
Create, change or delete up to 60 records; nothing is written unless all are valid. |
| POST | /crm/objects/{object}/records/upsert |
Change the record with this value in a unique field (match), or create it. |
| POST | /crm/objects/{object}/records/bulk |
Set a field, delete, link or unlink on up to 200 records. |
| GET | /crm/objects/{object}/automations |
The workspace automations offered on this object's records (their manual trigger names it). |
| POST | /crm/objects/{object}/records/run-automation |
Run one of them on up to 100 records, one run per record you may read. |
| GET, POST | /crm/objects/{object}/records/{record}/notes |
List a record's notes (pinned first), or write one. |
| PATCH, DELETE | /crm/objects/{object}/records/{record}/notes/{note} |
Change a note's text (its author), or delete it. |
| PUT | /crm/objects/{object}/records/{record}/notes/{note}/pin |
Pin a note, or take it off. |
| GET, POST | /crm/objects/{object}/records/{record}/tasks |
List the tasks about a record (open first), or add one. |
| PATCH, DELETE | /crm/objects/{object}/records/{record}/tasks/{task} |
Change or delete a task. |
| POST | /crm/objects/{object}/records/{record}/tasks/{task}/complete, /reopen |
Finish a task, or open it again. |
| GET, POST | /crm/objects/{object}/imports |
The last imports of a custom object, or upload a CSV. |
| GET, PUT | /crm/objects/{object}/imports/{import} |
Read an import, or map its columns. |
| POST | /crm/objects/{object}/imports/{import}/dry-run, /run, /rollback |
Check the file, import it, or undo it. |
| GET | /crm/objects/{object}/imports/{import}/errors |
The rows that failed, as a CSV. |
| POST, GET | /crm/objects/{object}/exports, /exports/{export} |
Queue a CSV of a list, then read it for the download link. |
| POST | /crm/objects/{object}/fields/{field}/files |
Upload one file (multipart file) for a Files field; the response is {id, name, size, mime, url}. |
| DELETE | /crm/objects/{object}/fields/{field}/files/{file} |
Drop an upload no record uses yet; queued. |
| GET | /crm/files/{file}/download |
The signed, expiring link a file's url points at; needs no token. |
Listing records
GET /crm/objects/{object}/records takes these query parameters:
filter: a tree of conditions, as JSON. A group is{"operator": "and", "children": [...]}(and,or, ornot, which is true when its children are not all true); a condition is{"field": "stage", "operator": "is", "value": "won"}. Composite fields take asub_field(a full name'sfirstorlast, a currency'scode). Groups nest four levels deep, up to 50 conditions.- A condition can name a field of the record a link points at with a dotted key, one hop deep:
{"field": "client.industry", "operator": "is", "value": "retail"}matches records linked to at least one client whose industry is retail. It works across every kind of link (one to many, many to one, many to many and the links of standard objects, such as a deal's company or a contact's deals) and uses the operators of the linked field.is_notandnot_containsmatch records where no linked record has the value, records with no link included. You can only filter by fields you may read, in objects you may read. sort: field keys,-for descending:-created_at,name. Records without a value come last. A field that links to at most one record (itssortableis true) sorts by the label of the linked record.search,per_page(1 to 100),cursor(frommeta.next_cursorormeta.prev_cursor),fields(which values to return),include(relation fields to load, one level deep),timezone.group_by(a select, boolean, member, date or single-valued relation field, withgroup_bucketofday,week,monthoryearfor dates) andaggregate(count,amount:sum,amount:avg,min,max,count_empty,count_not_empty,percent_empty,count_unique, andattached_notes:total_linksfor the total number of notes of the records listed). Groups and totals come back inmeta.view: start from a saved view; whatever else you send replaces that part of it.
The operators a field accepts depend on its type and are listed by /crm/field-types: text has
contains, not_contains, is, is_not, empty, not_empty; numbers add gt, gte, lt, lte;
dates add before, after, relative (this_week, last_month, or {"direction": "past", "amount": 7, "unit": "day"}), in_past, in_future and today; selects have in; relations match a record id with is.
A condition on a contact's name cannot be filtered; email and phone are matched whole with is.
Records and events
A record is {id, object, label, values, created_at, updated_at}; values is keyed by field key. For
contacts, companies, deals and tasks only the custom fields can be changed here, and they are created and
deleted at their own endpoints. A change to a custom object's records announces crm_record.created,
crm_record.updated, crm_record.deleted, crm_record.restored or, when two records are merged, crm_record.merged to
automations, carrying the object key, the record id and the keys of the fields that changed.
Notes and tasks
Any record can have notes and tasks, whatever its object. A note is rich text (cleaned before it is stored);
GET .../notes lists the pinned ones first and then the newest. Only a note's author changes its text; its
author, or someone who may delete in the workspace, deletes it. A task has a title, an optional description,
due_at and assignee_user_id (you, unless you name a member); GET .../tasks?status=open leaves out the finished
ones. Tasks are the workspace's ordinary tasks, so they also appear in GET /tasks, and they count against the open-task limit.
Adding a note or a task, changing it, finishing a task and deleting either announce crm_note.created, crm_note.updated,
crm_note.deleted, crm_task.created, crm_task.updated, crm_task.completed and crm_task.deleted to
automations with the object key, the record id and the note's or task's id.
Importing records from a CSV
Importing works on custom objects (people have their own import, and the other standard objects are created
where they live). It is five calls: upload the file (POST .../imports with a file, or the text in csv), map the
columns (PUT .../imports/{import} with mapping, a column name to a field key or ignore), check it
(POST .../dry-run), run it (POST .../run) and, if you want it back, undo it (POST .../rollback). The upload
suggests a mapping by matching column names to field names and keys. Poll the import for its status;
created + updated + restored + skipped + failed always equals the rows read.
- Name a unique field in
match_fieldto match rows to records that already exist;on_matchisupdate(the default) orskip. A matching record that was deleted is brought back. Empty cells never clear a stored value. - Each cell is read by the field's type: numbers accept
1,5and1.234,56, a select its label or value, a full nameAda LovelaceorLovelace, Ada, a lista; b. - A relation column holds the id or the name of the related record, several separated by
;. A name that matches none, or more than one, fails the row. A member column holds an email address, a name or an id. - The dry run walks the file exactly like the run and writes nothing, so its counts and the reasons rows fail are what
the run will meet, including two rows of the file clashing on a unique value.
GET .../errorshas every failed row. - A file may hold as many rows as the plan allows for contact imports. A run announces no
crm_record.*fact per row. - Undoing removes the records the import created unless someone has edited them or added a note or task since, and puts
back the values it changed unless they were edited since. A record that a
restrictrelation keeps from being deleted is counted asblockedinrollback.counts, not as removed.
Files in a record
A field of type file (settings max_files 1 to 10, max_size_mb up to 10 and accept, a list of images, pdfs,
documents, spreadsheets, audio, video, archives; empty accepts all) holds a list of files. Upload each file first
(POST .../fields/{field}/files, multipart file): you get {id, name, size, mime, url, attached, created_at}. Then set the
field of a record to the list of ids (a single id is fine for one file), on create or on update. Whatever else you send about
a file is ignored; the record shows {id, name, size, mime, url} for each. Sending the list without a file removes it from
the record, and null clears the field. A file can only be used by the field it was uploaded for, once, and only in the
workspace that uploaded it; otherwise the value is refused with 422 on values.<field>. The url is signed, expires after
15 minutes and is fetched without a token; it answers 423 while the security scan has not cleared the file. An upload that no
record uses within a day, a file taken off a record and the files of a purged field or object are removed from storage by a
background job. The plan needs file storage (422 on file without it). A CSV import leaves Files fields out and an export
writes the file names, separated by ;. The filter operators are empty and not_empty.
Exporting records
POST /crm/objects/{object}/exports queues a CSV of what a list shows: send view, filter, sort and search as the list
takes them (what you send replaces that part of the view), columns (field keys; the view's visible fields by default), or
records (the ids of ticked records). Poll GET .../exports/{export} for the signed, expiring download_url; it needs no token.
A relation is written as the names of the linked records and a member as an email address, so the file can be imported again.
People are exported from the contacts export, which keeps personal details to the roles that may see them.
Bulk actions
POST /crm/objects/{object}/records/bulk takes an action and up to 200 ids: update sets the values given,
delete queues the deletions, link and unlink add or remove the records on the relation field. Each record is its own
change, written like a single edit; the answer is {requested, succeeded, queued, failed: [{id, error}]}, so a record that
refuses (a duplicate in a unique field, a value the field rejects) does not stop the others.
Running an automation on records
GET /crm/objects/{object}/automations returns [{id, name, description}]: the active workspace automations whose manual
trigger names the object and that you may run. POST /crm/objects/{object}/records/run-automation takes one automation
id and up to 100 record ids and starts a run per record you may read; the answer is {requested, started, failed: [{id, error}], runs}.
A token needs automations:run as well as crm:read. An automation that is not offered on the object is a 422 on automation.
Duplicates and merges
A custom object names the fields that find duplicates in duplicate_criteria (field keys, or lists of keys that must
all match; up to 5; set it with PATCH /crm/objects/{object}). GET /crm/objects/{object}/duplicates returns the groups of
records that share a normalised value ({key, size, matched_on, records}, meta.total, meta.truncated).
POST /crm/objects/{object}/merges takes survivor and loser (record ids) and optional choices (field key to survivor
or loser) and answers 202 with the queued merge. The survivor keeps its values, fills its gaps from the loser unless a choice
says otherwise, and takes over the loser's links, notes, tasks and history; the loser is removed. Contacts and companies are
merged as a whole (no choices); deals and tasks field by field. GET .../merges lists the last merges, each with
by (who asked), merged_at, survivor_label and loser_label, changed (the fields the survivor took), moved
(counts by kind) and can_undo / undo_until. POST .../merges/{merge}/undo takes any of them back while can_undo is true
(14 days, survivor unchanged): a removed deal, task or company returns with its id. After the window the merge keeps its
facts and can_undo turns false. A merge announces crm_record.merged with the survivor's id and merged_record_id.
Record page layout
GET /crm/objects/{object}/layout returns tabs, each with sections, each with widgets (id, type, title,
props), plus version, is_default, updated_at and updated_by. An object nobody edited returns the built-in
layout (is_default: true, version: 0) and nothing is stored for it. Everyone who can open the object may read it; fields
and relations that are gone, and for a role those it cannot see, are left out. The owner and administrators also get
can_manage: true and a catalog of the fields, relations, widget types and limits a layout can use.
PUT replaces the whole document and saves it as the next version (the last 20 are kept; saving what is already saved adds
none). Send base_version with the version you read to get 409 when somebody saved in between. The document is checked:
widget type is one of fields, field, rich_text, related, notes, tasks, timeline, files, iframe, chart;
props are {group} or {fields: [keys]} (fields), {field} (field), {html} (rich_text, cleaned, up to 20,000 characters),
{relation} (related; null for all relations), {url, height} (iframe; https only, 120 to 1,200 pixels) and {chart_ref}
(chart; a placeholder until reporting renders it); notes, tasks, timeline and files take no props and can be used once.
A layout has 1 to 12 tabs, up to 20 sections per tab and 30 widgets per section. Ids are made up when left out. A refusal is
a 422 naming the part (tabs.0.sections.0.widgets.2.props.url). DELETE goes back to the built-in layout and answers it;
the layout in use stays among the versions. Only the owner and administrators may change, reset or restore a layout.
The data model as a document
GET /crm/schema returns the whole data model as {format: "formspring.crm.schema", version: 1, objects, relations} under
data: custom objects and the standard ones (referenced; only your own fields, views, permissions and layout on them), their
fields with options, the relations, the shared views of every type (filters including link.field conditions, sorts,
grouping, board columns), record page layouts, duplicate criteria and permissions (role flags, hidden and read-only fields,
row rules). Everything is named by key: objects, fields, options, roles, views (by name), never by id. It holds no records and
no secrets; the notes, tasks and files every object has and the system fields are not described. ?objects=a,b limits it to
those objects and the ones they relate to. Only the owner and administrators may call it (404 for other members, 402 on a
plan without custom objects); the token needs crm:read.
PUT /crm/schema takes the document as its body (or under document or data) and the options dry_run, prune,
allow_destructive and async in the query or the body. The token needs crm:write; dry_run needs only crm:read.
dry_run=trueanswers200with the plan and writes nothing.summarycountscreate,update,archive,restore,unchanged,destructiveandblocked;changeslists each entity (section:object,field,field_order,relation,object_settings,view,permissions,layout;object;key) withactionandchanges(path,from,to).unchangednames what is already as the document says.errorsholds what cannot be done (code: blocked: a field type or a relation's ends never change, an unknown role) and what the data model's rules refuse when the import is tried in a transaction that is rolled back (code: refused: plan limits, key rules, a view on a missing field, a field made unique over repeated values);rehearsedsays whether that was done (up to 300 changes).- Without
dry_runthe document is imported all or nothing in one transaction:200with the same shape andapplied: true, or422with the plan when anything is blocked or refused, and nothing has changed. Applying the same document again answersapplied: truewith no changes. - What the document leaves out stays, unless
prune=true, which archives it: fields, relations and objects keep their data and return when a document has them again (restore); unused shared views are removed in the background. Nothing is hard-deleted. - A change with
destructive: true(flags:field_with_data,options_removed,unique_tightened,object_with_records,relation_with_links) is refused with a422onallow_destructiveuntilallow_destructive=trueconfirms it. - More than 60 changes, or
async=true, answers202with{id, status: "queued", progress}and aLocationheader. The background run tries the whole import first, then applies it change by change;GET /crm/schema/applies/{id}returnsstatus(queued,running,succeeded,failed),progress(done,total),summary,errorsandfailure. Start the same document again after a failure: what was done is unchanged.
Every import and export writes an entry to the workspace's audit log. The agent tools are get_crm_schema, plan_crm_schema,
apply_crm_schema and get_crm_schema_apply; the SDK calls are schema, importSchema and schemaApply.
Permissions
GET /crm/objects/{object}/permissions returns, for every team role, its defaults, the override set on the object and what
that comes to, and the fields restricted per role. PUT replaces what it is sent: roles maps a role key to
{can_read, can_update, can_delete} (null inherits, true allows, false denies; denying read removes the other two) and
fields maps a field key to a role key to {can_read, can_update}. Only the owner and administrators may call either.
A field hidden from a role is left out of its records and exports and cannot be filtered, sorted or searched by it.
A role can also be limited to some of the records. roles.<role>.read_filter, update_filter and delete_filter take a
filter tree (the one lists and saved views use, with nested groups and link.field conditions) or null for none; a filter
key that is not sent is left as it is. A record outside the read_filter is a 404 for the role everywhere: lists, totals,
groups, search, exports, bulk calls, related records, the timeline, notes and tasks. update_filter and delete_filter
narrow it further and default to it. On a user field a condition may use "{me}" (the caller) and "{my_team}" (the
members who work with the caller: every member, or for one limited to some projects those who share a project);
anywhere else they are refused with a 422 keyed roles.<role>.<action>_filter. A rule that cannot be applied lets no record
through. The owner is never limited. The snapshot returns each role's rules as rows (read, update, delete) and
matches, the number of records the read rule lets through (counted for the caller where it uses {me} or {my_team}:
matches_as_actor). Creating a record is judged by can_update alone; the answer still contains the new record.
Tokens bound to a role
A token can be bound to a team role for the data model (crm_role when it is created, also on the tokens page and in the
create_token and update_token tools; list_tokens and GET /tokens show it). What it may do there is what the token's
abilities, its owner's own role and the bound role all allow: the role's object switches, hidden and read-only fields and
row rules apply in addition to the owner's, never instead. The bound role also decides whether the token may change the data
model or its permissions (only an admin-bound token, or an unbound one of an owner or administrator, may). Binding needs a
CRM ability, and a role that can read, change or delete anywhere the creator cannot is refused with a 422 keyed crm_role;
the owner can bind any role. A token made with a bound token is bound to the same role. A role that no longer exists, or an
object the role may not read, leaves the token with nothing there. Imports and exports asked for with a bound token keep the
role when they run later.
