Pagination & safe retries
Walk through large histories and retry writes without creating duplicate customers.
Follow the next cursor
List endpoints use cursor pagination in ascending creation order. Request per_page between 1 and 100; the default is 25. Read meta.pagination.has_more and pass next_cursor unchanged as the cursor query parameter on the next request. Keep the same endpoint and filters.
A malformed cursor returns 422. Cursors represent a position, not a snapshot; records added during pagination may appear on a later page. There is no total count or page number.
{
"data": [],
"meta": {
"pagination": {
"per_page": 25,
"next_cursor": null,
"has_more": false
}
}
}Give each write a stable operation key
POST requests that create customers, tickets, ticket replies or feature requests require an Idempotency-Key header. PUT and PATCH customer endpoints accept it optionally. Use a random UUID or a durable operation identifier: 1–128 printable ASCII characters without spaces. Use a different key for each intended change.
For the same API key, method, path and JSON content, a repeated request returns the saved success response and status, with Idempotency-Replayed: true. JSON object key order does not matter. Reusing the key with different content returns 409 idempotency_conflict.
Successful responses are kept encrypted for 24 hours by default. Validation and other failed writes are not cached. After expiry, the request is treated as new. Rotating or revoking the API key clears its replay records. PUT by external ID remains the preferred operation for ongoing profile synchronization.
Handle a network timeout
Keep the same body and Idempotency-Key when retrying a customer write after a timeout. Wait before retrying a 429, and use backoff for transient 5xx responses. Do not automatically retry a 4xx response without correcting its cause. Identity token issuance is not cached; request a fresh short-lived proof when needed.