Overview

Unifystays exposes your enabled hotel suppliers through one normalized API. Your system integrates once; supplier connections, static content and room mapping are handled by Unifystays. This page lists the conventions that apply to every endpoint. Each endpoint page then explains its own fields. New here? Follow the Quickstart, then read the Hotel Booking Flow.

Base URLs

Environment	Base URL	Use it for
Sandbox	`https://api-sandbox.unifystays.com`	Development and integration testing.
Production	`https://api.unifystays.com`	Live searches, bookings and cancellations.

Use the API key created for the same environment in the Unifystays portal. A Sandbox key on Production (or the reverse) is rejected with 403 API_ENVIRONMENT_MISMATCH. IDs, tokens and bookings never move between environments.

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. It tests how the API behaves and the full booking flow. It does not show Production coverage. Use destination IDs that Sandbox returns.

Authentication and headers

Every request needs your API key in x-api-key. Call the API from your backend only; never put a key in browser or mobile code.

curl "https://api-sandbox.unifystays.com/master-data/nationalities?limit=3" \
  -H "x-api-key: your_sandbox_api_key"

Header	Required	Description
`x-api-key`	Always	API key created in the portal for the environment you call. Send only this credential.
`content-type: application/json`	On requests with a body	All request bodies are JSON.
`Idempotency-Key`	Create Booking and Cancel Booking	Your unique key for one booking or cancellation attempt, up to 128 characters.
`X-Unifystays-End-User-IP`	Recommended on Create Booking	The traveler’s public IP address. Needed for some suppliers; if omitted, your server’s address is used.
`X-Unifystays-Contract-Version`	Optional	Send `2` or omit the header. See Versioning.
`X-Request-Id`	Optional	Your own trace ID (6 to 64 characters: letters, digits, `.`, `_`, `-`). Every response carries an `X-Request-Id`, yours if valid, otherwise generated.
`Last-Event-ID`	On a stream reconnect	The last event `id` you processed. See Stream Room Updates.

Errors for a missing or invalid key are 401. See Errors & Retries.

Response envelope

Hotel endpoints (everything under /hotels) return a JSON envelope:

{
  "contract_version": "2",
  "success": true,
  "message": "Hotels fetched successfully",
  "data": {}
}

Field	Meaning
`contract_version`	The response contract, `"2"`. Present on `/hotels/...` responses. Also returned as the `X-Unifystays-Contract-Version` response header.
`success`	`true` on success. A few calls use `success: false` with HTTP `200` as a normal outcome: prebook with `NOT_BOOKABLE`, and a booking that is `FAILED`. Always read `status` as well.
`message`	Plain English summary for logs. Do not parse it.
`data`	The endpoint-specific payload.

Other endpoints differ slightly:

Destination Autocomplete and Nationalities return success, message and data without contract_version.
Webhook management calls return the resource itself (and data plus meta for lists), without the envelope.
The room stream is Server-Sent Events, not an envelope. Each event body carries its own contract_version.

Errors use a different shape (success: false, request_id, error.code). See Errors & Retries.

Conventions

IDs and tokens

IDs are strings, except where noted: hotel_id is a string in responses but a number in destination.id; place_id is a number.
Prefixes help you recognize values: srch_ search, off_ offer, ra_ room allocation, br_ booking requirement, pbq7 prebooking, ubk_ booking, cq_ cancellation quote, evt_ webhook event.
Tokens and allocation IDs are opaque. Copy them unchanged; never parse, build or edit them. See the IDs and Tokens Cheat Sheet.

Dates, times and codes

Kind	Format
Stay dates (`check_in`, `check_out`)	`YYYY-MM-DD`, the hotel’s local date.
Timestamps (`created_at`, `expires_at`, …)	ISO 8601 in UTC, for example `2026-10-01T09:15:00.000Z`. Free-cancellation deadlines also give the hotel’s `local_datetime` with its `timezone`.
Hotel check-in and check-out times	`HH:MM:SS` in the hotel’s local time.
Country codes	ISO 3166-1 alpha-2 (`AE`, `IN`).
Nationality	The alpha-2 `iso_code` from Nationalities.
Currency	ISO 4217 (`USD`, `EUR`).
Child ages	Whole numbers 0 to 17, one entry per child. Send ages, not a count.

Money

Money appears in two forms. Always read the currency next to an amount.

Where	Form	How to display
Hotel search: `price.amount`, `supplier_prices[].amount` (Search Hotels, Search Price Updates)	Integer cents of `currency` for the whole stay (all nights and rooms). `null` when there is no quote.	Divide by 100.
Search filters: `price_min_usd_cents`, `price_max_usd_cents`, and `price_range` in Hotel Filters	Integer cents, always USD. The filter range is per night for one room; the search bounds are for the whole stay.	Divide by 100.
Offers and prebook (Get Hotel Rooms, Stream Room Updates, Prebook): `pricing` ledgers, penalties, `money_change`	Objects `{ "amount_minor", "currency", "currency_exponent" }`.	`amount_minor / 10^currency_exponent`. A currency with exponent 0 (JPY) is already whole units.
Bookings (Create Booking, Get Booking Details, List Bookings, Quote Cancellation): totals, penalty, charge	The same `{ amount_minor, currency, currency_exponent }` object.	Same formula.
Webhook events: `total_payable_to_supplier`, `cancellation_charge`	The same object.	Same formula.

Search amounts and offer amounts come from different steps: a search price is indicative, the offer from rooms is the price to charge, and the prebook offer is the confirmed one. Never mix them in one calculation. Unifystays does not collect payment from your guest; you decide your own selling price.

Optional and unknown values

null means “not known” or “does not apply”, not zero or “no”. Many lists are null or empty when there is nothing to show; check before you iterate.

Pagination

Endpoint	Style	How
Search Hotels	Cursor	Send `data.next_cursor` as `cursor`, with every other input unchanged. `null` on the last page. Start again without a cursor if you change a filter or sort.
List Bookings	Page	`page` (from 1) and `limit` (1 to 100, default 20). Continue while `data.meta.hasNextPage` is `true`.
Nationalities	Page	`page` and `limit` (1 to 300, default 250). One request returns the whole list; check `data.meta.totalPages`.
Webhook events and deliveries	Page	`page` and `limit` (1 to 100, default 20), with `meta.total_pages`.

Rate limits

Requests are limited per API key, per minute, by your plan:

Plan	Requests per minute
Free	20
Starter	60
Growth	150
Scale	400
Enterprise	Set in your contract

Get Search Price Updates and the room stream are not rate limited and never count toward your plan, so polling prices every 2 seconds is always safe. Your exact limit is in every other response:

Header	Meaning
`RateLimit-Limit`	Requests allowed per minute for this key.
`RateLimit-Remaining`	Requests left in the current one-minute window.
`Retry-After`	On `429` only: seconds until you can retry.

Above the limit the API returns 429 with code RATE_LIMITED. Wait for Retry-After, then retry with backoff. Cache stable data (Caching Strategy) to stay well below the limit. If you need a higher limit, contact support.

Monthly allowance

In Production, hotel search, rooms and content calls count toward your plan’s monthly allowance; Sandbox is unlimited. Price updates, room streams, prebook, booking and failed requests never count. When an allowance applies, responses also carry:

Header	Meaning
`X-Usage-Limit`	Counted calls included in this billing period.
`X-Usage-Remaining`	Counted calls left in this billing period.

On the Free plan, once the allowance is used up, requests return 429 with code MONTHLY_LIMIT_REACHED until the billing period resets; price updates and room streams keep working. On paid plans, calls above the allowance are billed as overage and are not blocked.

Idempotent booking

Create Booking and Cancel Booking require an Idempotency-Key. Generate one key per customer attempt and save it before the first request. After a timeout or an unreadable response, resend the same key with the identical body, or look the booking up with Find Booking by Idempotency-Key. A new key is a new attempt and can create another reservation. The same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED.

Time-sensitive data

Search prices, room offers and prebooking are live supplier data. Key times: search_id about 5 minutes, booking_token at most 15 minutes, prebooking_id until the offer’s lifecycle.expires_at, cancellation quote 5 minutes. The full list is in the Hotel Booking Flow. Destination and nationality data can be cached for 48 hours and 30 days. See Caching Strategy.

Webhooks

Use webhooks to receive booking updates without polling every booking. Endpoints are managed with the same x-api-key. Each delivery is signed with a separate endpoint secret. Start with the Webhooks guide and Verify Webhook Signatures, then use the webhook endpoint and delivery APIs to automate set-up and debugging.

Versioning and compatibility

The current contract version is 2, and it is served by default. You do not need to send the X-Unifystays-Contract-Version header. Hotel responses carry "contract_version": "2" and the X-Unifystays-Contract-Version: 2 response header; a request naming a version the API does not serve returns 406 CONTRACT_VERSION_UNSUPPORTED. Within a version we only make additive changes: new optional fields, new enum values and new endpoints. We never rename or remove a field or change its type. Build your client accordingly:

Ignore fields you do not recognize.
Handle unknown enum values gracefully. For example, treat an unknown price.status as no price, an unknown booking status as not final, and an unknown event type as one to ignore (still return 2xx).
Do not depend on field order or on the exact text of message fields.

A breaking change would ship as a new version that you opt into with the header, announced in advance.

API contract

Every endpoint page combines integration guidance with the generated OpenAPI contract: the complete required and optional fields, allowed values, response schemas, error responses and an interactive playground. Start with destination data

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

Overview

Base URLs

Authentication and headers

Response envelope

Conventions

IDs and tokens

Dates, times and codes

Money

Optional and unknown values

Rate limits

Monthly allowance

Idempotent booking

Time-sensitive data

Webhooks

Versioning and compatibility

API contract

​Base URLs

​Authentication and headers

​Response envelope

​Conventions

​IDs and tokens

​Dates, times and codes

​Money

​Optional and unknown values

​Pagination

​Rate limits

​Monthly allowance

​Idempotent booking

​Time-sensitive data

​Webhooks

​Versioning and compatibility

​API contract

Base URLs

Authentication and headers

Response envelope

Conventions

IDs and tokens

Dates, times and codes

Money

Optional and unknown values

Pagination

Rate limits

Monthly allowance

Idempotent booking

Time-sensitive data

Webhooks

Versioning and compatibility

API contract