API conventions
Predictable resource shapes, pagination, versions, and money values.
On this page
Work with opaque identifiers
Resource IDs are opaque strings. Store them as returned. Do not infer tenancy, resource type, or permissions from an identifier.
External references connect customer, traveler, lead, and order records to your system. They are unique within your integration and resource type. Email addresses are not identity or deduplication keys.
Follow the cursor
List responses use items, nextCursor, and hasMore. Reuse the cursor with the same filters and sort order. Page sizes are bounded by the published environment limits.
Updated-since filters support reconciliation, but the durable event cursor is the lossless recovery contract.
{
"items": [],
"nextCursor": null,
"hasMore": false
}Use the correct resource version
Updates and state-sensitive commands use If-Match. Get the version from the resource you are changing: case data, case commands, and staff work items have distinct preconditions.
A missing precondition returns 428. A stale version returns 412. Refresh the resource and review the changed state before retrying.
If-Match: "resource-version"Keep money and currency together
Money uses decimal strings and ISO currency codes. Do not use binary floating-point values for totals or combine amounts in different currencies.
The order contract uses a single invoice currency. Unknown or unpriced fees remain explicit; they must not appear as zero.
{ "amount": "125.00", "currency": "USD" }Dates and timestamps
Travel dates use YYYY-MM-DD. Event and operation timestamps use RFC 3339 UTC values. Preserve calendar dates as dates rather than converting them into local-time timestamps.