Conventions

Idempotency keys, cursor pagination, optimistic revisions and request limits, described as the server actually behaves rather than as guarantees.

Every endpoint shares these. What follows is what the server does, not a guarantee invented for the documentation — where a guarantee is narrower than you might assume, that is said.

Idempotency

Most mutations require an Idempotency-Key header, 8 to 128 characters, and refuse a request without one with 400. The reference names it on each endpoint that takes it — four POST endpoints do not: the two pricing previews, which write nothing, the download link, and POST /api/v1/bootstrap, which installs standard objects and is safe to repeat because an object already installed is left as it is.

Send the same key with the same body and you get the first answer back, replayed, without the work happening twice. Send the same key with a different body and the request is refused with 409 and the reason idempotency_key_reused.

Two limits on that guarantee are worth knowing.

A receipt is scoped to you and to the action, not globally. It is keyed on the user, the action and the key together, so the same key used by a different person, or by you against a different endpoint, is a different command. A key only has to be unique within what you yourself are doing.

A replay answers the body that was stored. If the shape of an endpoint’s response changes in a release, a key issued before it replays the older body. That is inherent to replaying a stored response, and it is why a key belongs to one request rather than being reused across a session.

Pagination

Two kinds of list exist, and they page differently.

Most lists — products, price books, quotes — take limit and after, and answer nextCursor. Pass nextCursor back as after for the next page, and stop when it is null.

Record lists take more: limit, dir, orderBy or view, relatedTo with via, and cursor or after. Four combinations are refused with 400, and they cannot be expressed in a parameter list:

• via requires relatedTo
• orderBy cannot be combined with view
• cursor requires one of orderBy or view
• after cannot be combined with either — page an ordered query with cursor

A cursor belongs to the ordering that produced it. The ordering — the sort, the direction, the related-record filter, the view — travels inside the cursor. Replay a cursor against a changed view and the request fails loudly with cursor_ordering_mismatch rather than answering a page that looks right and is not. Fetch from the first page again when the ordering changes.

total is counted on the first page only. A request with no after and no cursor answers a count; every later page answers total: null. The count is paid once rather than on every page, so hold the first page’s figure if you want to show one.

Revisions

Records, objects, fields, saved reports and the commercial policy carry a revision. An update sends the revision it was read at, and a stale one is refused with 409.

This is optimistic concurrency rather than a lock: nothing is held while you think. Read, send the revision you read, and handle the refusal by reading again.

Request limits

A request body is limited to 1 MB, except a note image upload, which is 4 MB. The limit is applied before the route runs, so an oversized request is refused with 413 whatever endpoint it was aimed at.

Headers

X-CRM-CSRF is not yours to send. The web application uses it for its own cookie-session writes; a bearer-token request does not take that path and does not need it. Credentialed CORS likewise allows the application’s own origin only — it does not apply to a server-to-server call, which sends no browser origin.

Dates and money

Timestamps are ISO 8601 strings in UTC. Date-only fields — a purchase date, a schedule’s start and end — are YYYY-MM-DD.

Money is a decimal string, never a number. Totals, unit prices, tax and discounts arrive as strings like "1234.56" so no value passes through a binary float. Parse them with a decimal library, and do not add them as numbers.