Skip to main content
The CRM API gives integrations the records the CRM app shows: companies, people, opportunities and records of custom types, with their notes, tasks and lists. Every call runs as the person who issued the token. Their CRM roles decide which types, records, fields and notes a call reaches, exactly as in the app.

Scopes

A token without the scope receives 403 INSUFFICIENT_SCOPE. A token cannot be limited to one type of record, only to reading or writing. With the scope, a call still cannot do more than its owner: a person whose role only reads companies gets 403 FORBIDDEN when they create one. If the owner loses a CRM role, the token loses those rights with the next call, without being reissued. If the owner’s account is deactivated or deleted, the token answers 401.

What the API does not offer

The mailbox connections and their credentials, the content of mail below the level a mailbox shares, the notes other people keep private, and the administration of roles are not part of the API. Types and fields are readable with Object types and are changed in the app.

Conventions

  • Visibility. A record, note or list the token owner may not see answers 404 CRM_NOT_FOUND or 404 NOT_FOUND, exactly like one that does not exist. A type the roles do not allow is missing from every list. A field the roles hide is missing from the response and cannot be written.
  • Short field keys. A request names a custom field by its short key, such as annualRevenue or amount. In a query (cql) the same field is cf.crm_<typeKey>_<fieldKey>, for example cf.crm_opportunity_amount.
  • Concurrent edits. Changing a record needs baseUpdatedAt, the contentUpdatedAt you read. If someone changed the record since, the request answers 409 CRM_CONFLICT_VERSION with the record as it is now in error.current. Read, merge and send again.
  • No idempotency key. Creating a company or a person with a domain or an e-mail address that already exists answers 409 CRM_DUPLICATE_CONTACT_POINT. That is how a repeated call is caught. Other records and lists are created twice if you send the call twice. A task or a note accepts an id you choose, so a repeat finds the one it made.
  • Strict bodies. Unknown fields are rejected with 422, not dropped.
  • Pages. Lists return nextCursor, which you pass back as cursor. A limit above the maximum of 100 is cut down to it. Notes, tasks and lists use their own maximum, stated on their pages.

Errors

On top of the general errors:
Last modified on November 13, 2026