All docs

CRM API

Contact timeline, notes, call log, tasks, lifecycle stages, companies, pipelines and deals over the REST API.

Updated . 28 min read.

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}/verification sends the person a one-time confirmation for a second email address (a link) or phone number (a text message). It answers 202; the message is queued. 422 says 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.status is pending or unverified, and an unverified second identifier never attaches a submission or payment to the contact (verification.identifies).
  • GET and POST /contacts/{contact}/consents take a channel of marketing_email (the default), sms, phone, whatsapp or postal. The top level of the answer is the marketing-email state; channels lists all five.
  • GET /contact-email-templates, POST, PATCH and DELETE /contact-email-templates/{id} manage the reusable messages; GET and PUT /contact-email-signature manage your own signature. Bodies are HTML, cleaned when saved, and a merge tag that does not exist ({{ nickname }}) answers 422. Deleting answers 202 and hides the template at once. All of this is part of the Scale plan.
  • POST /contacts/{contact}/email also takes template, format (plain or html) and signature.
  • PUT /crm/capture-owner takes one of form, funnel, survey, bio_page or booking_page to give that surface its own owners.
  • Notes, activities, a company's people and the consent history are paged with cursor and per_page; the answer carries meta.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, or not, which is true when its children are not all true); a condition is {"field": "stage", "operator": "is", "value": "won"}. Composite fields take a sub_field (a full name's first or last, a currency's code). 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_not and not_contains match 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 (its sortable is true) sorts by the label of the linked record.
  • search, per_page (1 to 100), cursor (from meta.next_cursor or meta.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, with group_bucket of day, week, month or year for dates) and aggregate (count, amount:sum, amount:avg, min, max, count_empty, count_not_empty, percent_empty, count_unique, and attached_notes:total_links for the total number of notes of the records listed). Groups and totals come back in meta.
  • 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_field to match rows to records that already exist; on_match is update (the default) or skip. 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,5 and 1.234,56, a select its label or value, a full name Ada Lovelace or Lovelace, Ada, a list a; 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 .../errors has 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 restrict relation keeps from being deleted is counted as blocked in rollback.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=true answers 200 with the plan and writes nothing. summary counts create, update, archive, restore, unchanged, destructive and blocked; changes lists each entity (section: object, field, field_order, relation, object_settings, view, permissions, layout; object; key) with action and changes (path, from, to). unchanged names what is already as the document says. errors holds 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); rehearsed says whether that was done (up to 300 changes).
  • Without dry_run the document is imported all or nothing in one transaction: 200 with the same shape and applied: true, or 422 with the plan when anything is blocked or refused, and nothing has changed. Applying the same document again answers applied: true with 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 a 422 on allow_destructive until allow_destructive=true confirms it.
  • More than 60 changes, or async=true, answers 202 with {id, status: "queued", progress} and a Location header. The background run tries the whole import first, then applies it change by change; GET /crm/schema/applies/{id} returns status (queued, running, succeeded, failed), progress (done, total), summary, errors and failure. 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.