IDs and Tokens Cheat Sheet - Unifystays API

A booking flow passes a handful of identifiers from one call to the next. Mixing them up is the most common integration mistake. This page lists every one: where it comes from, how long it is good for, and where it goes. Two rules apply to all of them:

Copy, never build. Tokens and allocation IDs are opaque. Do not parse, decode, edit, concatenate or derive one from another.
Stay in one environment. An ID from Sandbox does not exist in Production, and the other way round.

Search and room selection

Value	Comes from	Lifetime	Send it to	Store it?
`place_id` (number)	Destination Autocomplete result with `type = place`	Catalogue ID, long-lived	`destination.id` in Search Hotels; `place_id` in Hotel Filters	Yes, with the guest’s selection until they submit the search
`hotel_id` (string)	Autocomplete (`type = hotel`) or `data.hotels[].hotel_id` in search	Catalogue ID, long-lived	`destination.id` as a number for a single-hotel search; the path of Hotel Content and Hotel Rooms; `hotel_id` in Prebook	Yes. It is also the key for merging price updates and your content cache
autocomplete `id` (`place-…`, `hotel-…`)	Autocomplete	n/a	Nothing	No. It is a UI list key only
`nationality` (`iso_code`)	Nationalities	Cache 30 days	`nationality` in search, rooms	Yes. Send the same value in search and rooms
`search_id` (`srch_…`)	`data.search_id` of Search Hotels	About 5 minutes. Polling with `refresh_ids` extends it by 5 minutes	Search Price Updates path	Only for the life of the result page. After a `404`, search again
`next_cursor`	`data.next_cursor` of Search Hotels	Valid while you page with the same inputs	`cursor` of the next search request	Only while paging. Start again without a cursor if you change a filter or sort
`stream_id` and `sse_stream_url`	Get Hotel Rooms response	The search runs at most 45 seconds. A finished stream stays readable about 2 minutes	Open `sse_stream_url` with your API key (Stream Room Updates)	No. Open it immediately
Last SSE event `id`	`id:` line of each event	During the stream	`Last-Event-ID` header when you reconnect	Only in memory, while reading
`offer_id` (`off_…`)	Each entry of `options[]`	Until `lifecycle.expires_at`	Nothing at the room stage. Use it as a list key	No. Prebook issues a new `offer_id`
`offer_family_id`, `unifystays_room_id`, `unifystays_family_id`	Offers and room objects in the stream	For this search; built room IDs can be retired later	Nothing. Display and grouping only	No. Never use them as booking keys. A `tmp_` ID is valid for this search only
`booking_token`	`options[].booking_token` in the stream	At most 15 minutes (`lifecycle.expires_at`, from `quoted_at`)	`booking_token` in Prebook, together with the same `hotel_id`	Only until prebook. Never cache it

Checkout and booking

Value	Comes from	Lifetime	Send it to	Store it?
`prebooking_id` (`pbq7…`)	`data.prebooking_id` of Prebook	Until `data.offer.lifecycle.expires_at` (the supplier’s deadline, otherwise 15 minutes after the prebook call). Single use	`prebooking_id` in Create Booking	Keep with the checkout session until the booking is created
`data.offer.offer_id`	Prebook response (a new ID, `revision` goes up)	Same as the prebooking	`accepted_offer_id` in Create Booking and Confirm Hold	Yes, with the booking. It names the offer that was bought
`room_allocation_id` (`ra_…`)	`data.offer.rooms[]` of Prebook (the authoritative copy)	Same as the prebooking	`rooms[].room_allocation_id` in Create Booking, once per room	Yes, with the booking. It joins guests to rooms in booking details
`requirement_id` (`br_…`)	`data.offer.booking_requirements[]` of Prebook	Bound to that offer	`answers[].requirement_id` in Create Booking	No. Read it again from each prebook
`Idempotency-Key`	You generate it	Yours to keep. Up to 128 characters, private to your organization	Header of Create Booking and of Cancel Booking; header of Find Booking by Idempotency-Key	Yes, before the first request, next to your own order number
`X-Unifystays-End-User-IP`	Your guest’s public IP	Per request	Header of Create Booking	No
`guest_id`	You generate it	One request	`guests[].guest_id` in Create Booking	Optional. It only labels guests in error messages

After booking

Value	Comes from	Lifetime	Send it to	Store it?
`booking_id` (`ubk_…`)	`data.booking_id` of Create Booking	Permanent	Path of Get Booking Status, Get Booking Details, Cancellation Quote, Cancel Booking, Confirm Hold	Yes, immediately. It is the key for everything after booking
`provider.booking_id`, `provider.booking_code`	Booking status and details	Permanent	Support requests	Yes. These are supplier references, not guest-facing numbers
`provider.hotel_confirmation_number`	Booking status and details; can arrive after `CONFIRMED`	Permanent	Show it to the guest and print it on the voucher	Yes, once present. Watch for the `booking.updated` webhook
`quote_id` (`cq_…`)	`data.quote_id` of Cancellation Quote	5 minutes, or sooner if the penalty is about to change. Single use	`cancellation_quote_id` in Cancel Booking	No. Request a new quote if it expires
`hold_deadline_at`	Booking status on an `ON_HOLD` booking	A fixed time	Confirm before it	Yes, to show a countdown

Webhooks and support

Value	Comes from	Lifetime	Use	Store it?
Webhook event `id` (`evt_…`)	Body of each delivery and the `X-UnifyStay-Webhook-Id` header	Same on every retry and replay	Your deduplication key	Yes
`data.object.version`	Body of each booking event	Rises by one with every event of a booking	Apply an event only if it is higher than the version you hold	Yes, per booking
Endpoint `id` (UUID)	Create Webhook Endpoint	Until you delete the endpoint	Update, rotate, test and delete calls	Yes
`signing_secret` (`whsec_…`)	Create Webhook Endpoint, shown once	Until rotated	Verify the signature of every delivery	Yes, in a secret manager only
`X-Request-Id`	Response header on every response (also `request_id` in error bodies). You may send your own	One request	Quote it to support	Log it for every failed call

Where each value goes next

place_id / hotel_id ─► search ─► search_id ─► price polling
                          │
                  hotel_id ─► rooms ─► sse_stream_url ─► booking_token
                                                              │
                       hotel_id + booking_token ─► prebook ─► prebooking_id
                                                              offer_id
                                                              room_allocation_id[]
                                                              booking_requirements[]
                                                              │
        Idempotency-Key + prebooking_id + accepted_offer_id + rooms[] ─► book ─► booking_id
                                                              │
              booking_id ─► status / details / cancellation quote ─► quote_id ─► cancel

The three most common mistakes: booking with a room or family ID instead of booking_token and room_allocation_id; creating a new Idempotency-Key for an uncertain retry; and sending the autocomplete id instead of place_id or hotel_id.

Next: see the Hotel Booking Flow for the order of calls, or Errors & Retries when a call fails.