Quickstart

This walkthrough makes every call of the booking flow once, in order, from your terminal. Each step shows the smallest request that works and the few response fields you need for the next step. It takes about 15 minutes. You need curl and jq. Run all steps in the same shell so the variables carry over.

Sandbox only has hotels in 12 test cities: Paris, Los Angeles, Dubai, Rome, Naples, Istanbul, Tokyo, Bangkok, Chiang Mai, New Delhi, Ho Chi Minh City and Marrakech. This guide uses Dubai. If you search for another city, Sandbox returns an empty result. That does not mean your key or request is wrong. Use IDs that Sandbox returns, not IDs copied from Production. See Sandbox test cities.

1. Set up Sandbox and your environment

Sign in at unifystays.com, choose Sandbox, add and enable at least one supplier, and create a Sandbox API key. See Portal & Environments.

export UNIFYSTAYS_BASE_URL="https://api-sandbox.unifystays.com"
export UNIFYSTAYS_API_KEY="your_sandbox_api_key"

# Stay dates. Use dates well in the future so that a refundable offer's free
# cancellation window ends more than 2 days from now (see step 7).
export CHECK_IN="2026-12-10"
export CHECK_OUT="2026-12-13"

Check that the key works:

curl -s "$UNIFYSTAYS_BASE_URL/master-data/nationalities?search=ind&limit=3" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" | jq '.data.items[].iso_code'

You should see "IN" (and possibly others). A 401 means the key is missing, wrong, or from the other environment.

2. Find a destination

curl -s "$UNIFYSTAYS_BASE_URL/destinations/autocomplete?q=dubai&types=place&limit=5" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" | jq '.data.results'

Send at least 3 characters. Pick a result with "type": "place":

{ "type": "place", "display_name": "Dubai", "place_id": 2930267, "hotel_count": 10983 }

You need	Where	Used for
`place_id`	`data.results[].place_id`	`destination.id` in the search
`type`	`data.results[].type`	`destination.type` in the search

export PLACE_ID=2930267   # use a place_id returned by your environment

Never send the result’s id field (place-2930267). It is only a UI key. For a hotel result send type: "hotel" and its hotel_id as a number. Details: Destination Autocomplete.

3. Search hotels

curl -s "$UNIFYSTAYS_BASE_URL/hotels/search" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -d "{
    \"destination\": { \"type\": \"place\", \"id\": $PLACE_ID },
    \"check_in\": \"$CHECK_IN\",
    \"check_out\": \"$CHECK_OUT\",
    \"nationality\": \"IN\",
    \"rooms\": [ { \"adults\": 2, \"child_ages\": [] } ],
    \"limit\": 20,
    \"pricing_mode\": \"instant\"
  }" > search.json

jq '{search_id: .data.search_id, refresh_status: .data.refresh_status, hotels: [.data.hotels[] | {hotel_id, hotel_name, status: .price.status}]}' search.json

You need	Where	Used for
`search_id`	`data.search_id`	Polling prices in step 4
`refresh_status`	`data.refresh_status`	`PENDING`: suppliers are still being asked, so poll. `NA`: prices are final
`hotels[].hotel_id`	`data.hotels[]`	Rooms, content, prebook
`hotels[].price.status`	`data.hotels[].price.status`	What to show on each card (`live`, `recent`, `checking`, `no_price`, `unpriced`)

export SEARCH_ID=$(jq -r '.data.search_id' search.json)

Always send the traveller’s real nationality; suppliers price by it. Details: Search Hotels.

4. Poll for prices

Cards with price.status = "checking" are still being priced. Poll every 2 seconds while the result page is visible.

for i in $(seq 1 10); do
  curl -s "$UNIFYSTAYS_BASE_URL/hotels/search/$SEARCH_ID/prices" \
    -H "x-api-key: $UNIFYSTAYS_API_KEY" > prices.json
  STATUS=$(jq -r '.data.status' prices.json)
  echo "poll $i: $STATUS"
  [ "$STATUS" = "COMPLETE" ] || [ "$STATUS" = "EXPIRED" ] && break
  sleep 2
done

jq '.data.hotels[] | select(.price.status == "live" or .price.status == "recent")
    | {hotel_id, amount: .price.amount, currency: .price.currency, status: .price.status}' prices.json

You need	Where	Used for
`data.status`	top of the response	Stop on `COMPLETE` or `EXPIRED`
`hotels[].price.status`	each entry	`live` and `recent` carry a number; `checking` keeps polling; `no_price` means sold out; `unpriced` means unavailable
`hotels[].price.amount`	each entry	Whole-stay total in cents of `price.currency`. `275000` is 2,750.00. `null` unless `live` or `recent`

Pick a hotel that has a price:

export HOTEL_ID=$(jq -r '[.data.hotels[] | select(.price.status=="live" or .price.status=="recent")][0].hotel_id' prices.json)
echo "$HOTEL_ID"

The search price is indicative. The price you charge comes from the next steps. Details: Get Search Price Updates.

5. Get rooms and read the stream

Send the same dates, occupancy and nationality as the search.

curl -s "$UNIFYSTAYS_BASE_URL/hotels/$HOTEL_ID/rooms" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -d "{
    \"check_in\": \"$CHECK_IN\",
    \"check_out\": \"$CHECK_OUT\",
    \"nationality\": \"IN\",
    \"rooms\": [ { \"adults\": 2, \"child_ages\": [] } ]
  }" > rooms.json

jq '{stream_id: .data.stream_id, sse_stream_url: .data.sse_stream_url, suppliers: .data.providers_queried}' rooms.json
export SSE_URL=$(jq -r '.data.sse_stream_url' rooms.json)

You need	Where	Used for
`data.sse_stream_url`	rooms response	The stream to open right away
`data.unifystays_rooms[]`	rooms response	Room families already known (empty the first time a hotel is searched)

Now read the stream. The offers arrive as provider_options events; the last event is done. The connection stays open after done, so this command stops by itself after 50 seconds. (A real client closes the connection at done.)

curl -sN --max-time 50 "$UNIFYSTAYS_BASE_URL$SSE_URL" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "accept: text/event-stream" > stream.txt

# Last event: how did the search end?
grep '^data: ' stream.txt | sed 's/^data: //' \
  | jq -c 'select(.event_type=="done") | {status, total_options, providers}'

# Offers: one line per bookable offer
grep '^data: ' stream.txt | sed 's/^data: //' \
  | jq -c 'select(.event_type=="provider_options") | .options[]
    | {offer_id, provider_code, refundability: .cancellation.refundability,
       total: .pricing.native_ledger.totals[0].total, expires_at: .lifecycle.expires_at,
       booking_token}' > offers.jsonl
cat offers.jsonl

You need	Where	Used for
`done.status`	last event	`COMPLETE`, `PARTIAL` (show what you have) or `FAILED` (search again)
`options[].booking_token`	each offer	The one value that selects an offer for prebook. Valid for at most 15 minutes
`options[].pricing.native_ledger.totals[0].total`	each offer	Price as `{ amount_minor, currency, currency_exponent }`. Divide `amount_minor` by `10^currency_exponent`
`options[].cancellation.refundability`, `free_cancellation_until`	each offer	Cancellation badge

Choose an offer. For this walkthrough take a refundable one:

export BOOKING_TOKEN=$(jq -r 'select(.refundability=="REFUNDABLE") | .booking_token' offers.jsonl | head -1)
echo "$BOOKING_TOKEN"

Browsers cannot send x-api-key with EventSource, so open the stream from your server and forward events to the browser. Reconnecting, family objects and room cards are covered in Stream Room Updates and Get Hotel Rooms.

6. Prebook the chosen offer

Prebook asks the supplier right now whether the room and price still hold.

curl -s "$UNIFYSTAYS_BASE_URL/hotels/prebook" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -d "{ \"hotel_id\": \"$HOTEL_ID\", \"booking_token\": \"$BOOKING_TOKEN\" }" > prebook.json

jq '{decision: .data.revalidation.decision, prebooking_id: .data.prebooking_id,
     offer_id: .data.offer.offer_id, expires_at: .data.offer.lifecycle.expires_at,
     rooms: [.data.offer.rooms[] | {room_allocation_id, occupancy}]}' prebook.json

You need	Where	Used for
`data.revalidation.decision`	prebook response	`READY_TO_BOOK`: continue. `RECONFIRMATION_REQUIRED`: show the new price and continue only if the guest accepts. `NOT_BOOKABLE`: go back to rooms
`data.prebooking_id`	prebook response	`prebooking_id` in the booking. Single use, expires at `offer.lifecycle.expires_at`
`data.offer.offer_id`	prebook response	`accepted_offer_id` in the booking
`data.offer.rooms[].room_allocation_id` and `occupancy`	prebook response	One entry per room in the booking, with the right number of adults and children
`data.offer.booking_requirements[]`	prebook response	The guest fields to collect (`requirement_id`, `code`, `scope`, `required`)

export PREBOOKING_ID=$(jq -r '.data.prebooking_id' prebook.json)
export OFFER_ID=$(jq -r '.data.offer.offer_id' prebook.json)
export ROOM_ALLOCATION_ID=$(jq -r '.data.offer.rooms[0].room_allocation_id' prebook.json)

# The questions to put in your checkout form:
jq '.data.offer.booking_requirements[] | {requirement_id, code, scope, required, allowed_values}' prebook.json

If decision is NOT_BOOKABLE, prebooking_id is null: go back to step 5. Details: Prebook a Room.

7. Create the booking

Generate one Idempotency-Key for this booking attempt and keep it. Build the answers from the requirement_id values printed in step 6; never invent IDs. The example below is for one room with two adults and the common title, first name and last name requirements. If your offer asks for more (for example email or phone for the lead guest), add those answers too.

export IDEMPOTENCY_KEY="quickstart-$(date +%s)"
export REQ_TITLE=$(jq -r '.data.offer.booking_requirements[] | select(.code=="TITLE") | .requirement_id' prebook.json | head -1)
export REQ_FIRST=$(jq -r '.data.offer.booking_requirements[] | select(.code=="FIRST_NAME") | .requirement_id' prebook.json | head -1)
export REQ_LAST=$(jq -r '.data.offer.booking_requirements[] | select(.code=="LAST_NAME") | .requirement_id' prebook.json | head -1)

curl -s "$UNIFYSTAYS_BASE_URL/hotels/book" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "X-Unifystays-End-User-IP: 8.8.8.8" \
  -d "{
    \"prebooking_id\": \"$PREBOOKING_ID\",
    \"accepted_offer_id\": \"$OFFER_ID\",
    \"rooms\": [
      {
        \"room_allocation_id\": \"$ROOM_ALLOCATION_ID\",
        \"guests\": [
          { \"guest_id\": \"guest_1\", \"guest_type\": \"ADULT\", \"is_lead_guest\": true,
            \"answers\": [
              { \"requirement_id\": \"$REQ_TITLE\", \"value\": \"MR\" },
              { \"requirement_id\": \"$REQ_FIRST\", \"value\": \"Test\" },
              { \"requirement_id\": \"$REQ_LAST\", \"value\": \"Guest\" }
            ] },
          { \"guest_id\": \"guest_2\", \"guest_type\": \"ADULT\", \"is_lead_guest\": false,
            \"answers\": [
              { \"requirement_id\": \"$REQ_TITLE\", \"value\": \"MRS\" },
              { \"requirement_id\": \"$REQ_FIRST\", \"value\": \"Test\" },
              { \"requirement_id\": \"$REQ_LAST\", \"value\": \"Guest\" }
            ] }
        ]
      }
    ]
  }" > book.json

jq '{status: .data.status, booking_id: .data.booking_id, processing_reason: .data.processing_reason}' book.json
export BOOKING_ID=$(jq -r '.data.booking_id' book.json)

Use the real traveller’s public IP in X-Unifystays-End-User-IP in production (some suppliers require it). For a multi-room search, send one rooms[] entry for every room of the prebook.

You need	Where	Used for
`data.booking_id`	booking response	The key for every later call. Save it now, next to your order
`data.status`	booking response	`PROCESSING` (queued with the supplier) or `AWAITING_REVIEW`. Never a confirmation

The response to Create Booking is never a confirmed reservation. If the call times out, do not create a new key. Look the booking up with the same key:

curl "$UNIFYSTAYS_BASE_URL/hotels/book/by-idempotency-key" -H "x-api-key: $UNIFYSTAYS_API_KEY" -H "Idempotency-Key: $IDEMPOTENCY_KEY"

A booking whose free-cancellation window ends within 2 days, or a non-refundable offer, starts as AWAITING_REVIEW and waits for approval in the portal. Nothing is reserved until then. Use a refundable offer with dates well ahead, as in this walkthrough, to get PROCESSING. Details: Create Booking.

8. Track the booking

Poll the status, or receive a webhook (see below).

for i in $(seq 1 24); do
  curl -s "$UNIFYSTAYS_BASE_URL/hotels/book/$BOOKING_ID" \
    -H "x-api-key: $UNIFYSTAYS_API_KEY" > status.json
  jq -c '{status: .data.status, is_terminal: .data.is_terminal, hotel_confirmation_number: .data.provider.hotel_confirmation_number, next_poll_after_ms: .data.next_poll_after_ms}' status.json
  [ "$(jq -r '.data.is_terminal' status.json)" = "true" ] && break
  sleep 5
done

You need	Where	Used for
`data.status`	status response	`CONFIRMED` (issue the voucher), `FAILED` (tell the guest), `AWAITING_REVIEW`, `PROCESSING` (keep waiting)
`data.is_terminal`	status response	Stop polling when `true`
`data.provider.hotel_confirmation_number`	status response	Show it to the guest. It can arrive after `CONFIRMED`
`data.available_actions`	status response	Drive your buttons (`CANCEL`, `CONFIRM_HOLD`, `CONTACT_SUPPORT`…)

When it is CONFIRMED, read the full record with GET /hotels/book/$BOOKING_ID/details. See Get Booking Status and Get Booking Details.

Or receive webhooks instead of polling

curl -s "$UNIFYSTAYS_BASE_URL/webhooks/endpoints" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -d '{ "name": "Sandbox bookings", "url": "https://your-tunnel.example.com/webhooks/unifystays", "event_types": ["booking.*"] }' \
  | jq '{id, signing_secret}'

The signing_secret is shown once. Verify every delivery with it (Verify Webhook Signatures), deduplicate on the event id, and apply events by data.object.version. The full guide is Webhooks.

9. Cancel the booking

Cancelling takes two calls: get a quote that shows the penalty, then cancel with the quote. This only works on a CONFIRMED (or ON_HOLD) booking whose available_actions contains CANCEL.

curl -s "$UNIFYSTAYS_BASE_URL/hotels/book/$BOOKING_ID/cancellation-quote" \
  -X POST -H "x-api-key: $UNIFYSTAYS_API_KEY" > quote.json

jq '{quote_id: .data.quote_id, penalty_status: .data.penalty_status, penalty: .data.penalty, expires_at: .data.expires_at}' quote.json
export QUOTE_ID=$(jq -r '.data.quote_id' quote.json)

You need	Where	Used for
`data.quote_id`	quote response	`cancellation_quote_id` in the cancel call. Single use, valid 5 minutes
`data.penalty_status` and `data.penalty`	quote response	Show it to the guest: `NO_CHARGE`, `KNOWN` (amount in minor units) or `UNKNOWN` (never show as zero)

After the guest accepts the penalty:

curl -s "$UNIFYSTAYS_BASE_URL/hotels/book/$BOOKING_ID/cancel" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "Idempotency-Key: cancel-$IDEMPOTENCY_KEY" \
  -d "{ \"cancellation_quote_id\": \"$QUOTE_ID\" }" | jq '{status: .data.status}'

The result is CANCELLED or CANCELLATION_PENDING. Do not tell the guest it is cancelled until the status is CANCELLED (poll step 8 or wait for booking.cancelled). Details: Quote Cancellation and Cancel Booking.

Hotel Booking Flow

Sequence diagram, expiries, error recovery and UI guidance.

IDs and Tokens Cheat Sheet

What to store, what to send back, how long each value lives.

Errors & Retries

Every error code and what to do about it.

Launch Checklist

Go-live steps for Production.

Get started

Build your integration

Operate

1. Set up Sandbox and your environment

2. Find a destination

3. Search hotels

4. Poll for prices

5. Get rooms and read the stream

6. Prebook the chosen offer

7. Create the booking

8. Track the booking

Or receive webhooks instead of polling

9. Cancel the booking

What to read next

Hotel Booking Flow

IDs and Tokens Cheat Sheet

Errors & Retries

Launch Checklist

​1. Set up Sandbox and your environment

​2. Find a destination

​3. Search hotels

​4. Poll for prices

​5. Get rooms and read the stream

​6. Prebook the chosen offer

​7. Create the booking

​8. Track the booking

​Or receive webhooks instead of polling

​9. Cancel the booking

​What to read next

Hotel Booking Flow

IDs and Tokens Cheat Sheet

Errors & Retries

Launch Checklist

1. Set up Sandbox and your environment

2. Find a destination

3. Search hotels

4. Poll for prices

5. Get rooms and read the stream

6. Prebook the chosen offer

7. Create the booking

8. Track the booking

Or receive webhooks instead of polling

9. Cancel the booking

What to read next