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_FOUNDor404 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
annualRevenueoramount. In a query (cql) the same field iscf.crm_<typeKey>_<fieldKey>, for examplecf.crm_opportunity_amount. - Concurrent edits. Changing a record needs
baseUpdatedAt, thecontentUpdatedAtyou read. If someone changed the record since, the request answers409 CRM_CONFLICT_VERSIONwith the record as it is now inerror.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 anidyou 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 ascursor. Alimitabove the maximum of 100 is cut down to it. Notes, tasks and lists use their own maximum, stated on their pages.