> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Base URLs, authentication, response conventions, and booking idempotency for the Unifystays API.

Unifystays exposes your enabled hotel suppliers through one normalized API. Your
system integrates once; supplier credentials, activation, static content
synchronization, and supplier-specific mappings are managed by Unifystays.

## 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](https://unifystays.com).

## Authentication and Headers

Every API request must include the API key in `x-api-key`.

```bash theme={null}
curl "https://api-sandbox.unifystays.com/master-data/nationalities" \
  -H "x-api-key: your_sandbox_api_key" \
  -H "language: en"
```

| Header            | Required            | Description                                                     |
| ----------------- | ------------------- | --------------------------------------------------------------- |
| `x-api-key`       | Yes                 | API key created in the portal for the selected environment.     |
| `language`        | Recommended         | Language code for localized content.                            |
| `Idempotency-Key` | `POST /hotels/book` | Unique key for one customer booking attempt.                    |
| `X-Request-Id`    | Optional            | Your client trace ID. Every response also includes this header. |

<Warning>
  Make API calls from your backend. Do not expose Unifystays API keys in
  browser or mobile application code.
</Warning>

## Response Conventions

Most successful endpoints return a JSON envelope containing a success indicator,
a human-readable message, and endpoint-specific `data`.

```json theme={null}
{
  "success": true,
  "message": "Request completed",
  "data": {}
}
```

Prebook uses `status` as its success indicator. Always use the operation-level
schema below each endpoint for its exact response contract. Record the returned
`X-Request-Id` so Unifystays support can trace a request.

## Idempotent Booking

`POST /hotels/book` requires an `Idempotency-Key`. Generate one key for a single
customer booking attempt and persist it before making the request. If the
network times out or the client cannot read the response, retry with the same
key and the identical request body.

Never create a new key for an uncertain retry; a new key represents a new
booking attempt and can create another reservation.

## Time-Sensitive Data

* Cache destination autocomplete results for 48 hours and nationalities for 30
  days. See [Caching Strategy](/guides/caching-strategy).
* Refresh supplier-backed search prices and room options as the customer moves
  through checkout.
* Prebook immediately before booking to verify the selected room's current
  availability and price.
* Poll booking status after booking or cancellation rather than assuming a
  supplier operation is final.

## API Contract

Every endpoint page below combines integration guidance with the generated
OpenAPI contract. The contract contains the complete required and optional
fields, allowed values, response schemas, error responses, examples, and the
interactive request playground.

[Start with destination data](/api-reference/destination-autocomplete)