> ## 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.
# Create Booking
> Create an idempotent hotel booking from a successful Unifystays prebooking response.
Create a booking only after a successful
[Prebook a Room](/api-reference/prebook) response. This endpoint is
idempotent and requires an `Idempotency-Key` header for every request.
## Request Example
```bash theme={null}
curl "$UNIFYSTAYS_BASE_URL/hotels/book" \
-X POST \
-H "content-type: application/json" \
-H "x-api-key: $UNIFYSTAYS_API_KEY" \
-H "language: en" \
-H "Idempotency-Key: order-2987349823-booking-1" \
-d '{
"unifystays_prebooking_id": "pbq1.bjNQb1Y5R2hRWEg.k6jQ3nW4cF1nL4MWvN7A9Q",
"rooms": [
{
"room_ref": "1",
"unifystays_room_id": "1321374576",
"guests": [
{
"title": "Mr",
"first_name": "Shubham",
"last_name": "Gupta",
"type": "Adult"
},
{
"title": "Mrs",
"first_name": "Aarohi",
"last_name": "Gupta",
"type": "Adult"
}
]
}
]
}'
```
## Idempotency Rules
Generate one unique key for one customer booking attempt. Persist it before
the request. On a network timeout or unreadable response, retry with the
**same key and identical request body**.
Never generate another key for an uncertain retry. A new key represents a new
attempt and can result in a second reservation.
## Build the Booking Body
* Send `unifystays_prebooking_id` from the prebook response.
* Send rooms in the same count and order returned by prebook.
* Use each prebook `room_ref` to attach the correct guests to that room.
* Include every required guest field from the OpenAPI contract.
* Supply document fields such as `pan` or `passport` when the prebook result
indicates the supplier requires them.
## Track the Outcome
The response contains a stable `booking_id` and unified status. Use
[Get Booking Status](/api-reference/get-booking-status) as the source of truth
after the request returns.
| Status | Meaning |
| ---------------------- | ----------------------------------------------------------- |
| `PROCESSING` | Booking request accepted and still being finalized. |
| `CONFIRMED` | Booking is confirmed. |
| `ON_HOLD` | Supplier handling may still need attention or confirmation. |
| `FAILED` | Booking could not be completed. |
| `CANCELLATION_PENDING` | A cancellation request is being processed. |
| `CANCELLED` | Booking cancellation is complete. |
Use `is_terminal` from the status response when deciding whether to stop
polling rather than relying only on a status name.
Booking contains guest personal data. Send it only from your trusted backend
and avoid writing unprotected guest information to client-side logs.
The OpenAPI section below documents all booking fields, guest structures,
document fields, response statuses, and errors.
## OpenAPI
````yaml reference/openapi.json POST /hotels/book
openapi: 3.0.0
info:
title: Unifystays API
description: >-
One unified hotel API across suppliers. Integrate once, then enable and
manage suppliers from the Unifystays portal.
version: '1.0'
contact: {}
servers:
- url: https://api-sandbox.unifystays.com
description: Sandbox
- url: https://api.unifystays.com
description: Production
security:
- x-api-key: []
tags: []
paths:
/hotels/book:
post:
tags:
- Hotels
summary: Create hotel booking (async-safe, idempotent)
description: >-
Creates a booking request and returns a stable booking state object.
This endpoint is **idempotent** and requires `Idempotency-Key`.
Response status can be `PROCESSING`, `CONFIRMED`, `ON_HOLD`, `FAILED`,
`CANCELLATION_PENDING`, or `CANCELLED`.
Call `GET /hotels/book/{booking_id}` to fetch latest state.
operationId: HotelBookingController_book
parameters:
- name: Idempotency-Key
in: header
description: >-
Unique key per booking attempt from client. Reusing the same key
with same payload returns the same booking object.
required: true
schema:
type: string
- name: language
description: Enter language code(ex. en)
in: header
schema: {}
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HotelBookingRequestDto'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HotelBookingResponseDto'
'400':
description: Validation or booking creation error.
components:
schemas:
HotelBookingRequestDto:
type: object
properties:
unifystays_prebooking_id:
type: string
description: >-
Prebooking token from prebook response
(`data.unifystays_prebooking_id`).
example: pbq1.bjNQb1Y5R2hRWEg.k6jQ3nW4cF1nL4MWvN7A9Q
rooms:
description: >-
Room-wise guest details. Must match prebooking rooms in count and
order.
type: array
items:
$ref: '#/components/schemas/BookingRoomDto'
required:
- unifystays_prebooking_id
- rooms
HotelBookingResponseDto:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Booking request accepted and is being processed.
data:
$ref: '#/components/schemas/BookingStatusDataDto'
required:
- success
- message
- data
BookingRoomDto:
type: object
properties:
room_ref:
type: string
description: >-
Room reference from prebooking response `rooms[].room_ref` to
preserve room order mapping.
example: '1'
unifystays_room_id:
type: string
description: Unifystays room id mapped for this room.
example: '1321374576'
guests:
description: All guests in one room (adults + children). One object per room.
type: array
items:
$ref: '#/components/schemas/GuestInfoDto'
required:
- room_ref
- unifystays_room_id
- guests
BookingStatusDataDto:
type: object
properties:
booking_id:
type: string
example: ubk_eGQ0dW9uV1Vi
status:
type: string
enum:
- PROCESSING
- CONFIRMED
- ON_HOLD
- FAILED
- CANCELLATION_PENDING
- CANCELLED
example: PROCESSING
is_terminal:
type: boolean
example: false
provider:
$ref: '#/components/schemas/BookingProviderStatusDto'
next_poll_after_ms:
type: object
description: Client hint to re-check booking status. Null when terminal.
example: 5000
nullable: true
created_at:
type: string
example: '2026-04-15T12:12:11.000Z'
updated_at:
type: string
example: '2026-04-15T12:12:11.000Z'
metadata:
type: object
additionalProperties: true
nullable: true
required:
- booking_id
- status
- is_terminal
- provider
- created_at
- updated_at
GuestInfoDto:
type: object
properties:
title:
type: string
enum:
- Mr
- Mrs
- Ms
- Miss
- Master
example: Mr
first_name:
type: string
example: Shubham
last_name:
type: string
example: Gupta
type:
type: string
enum:
- Adult
- Child
example: Adult
pan:
type: string
description: Optional PAN card number for provider compliance when required.
example: AAACA1111A
passport:
type: string
description: Optional passport number for provider compliance when required.
example: P1234567
required:
- title
- first_name
- last_name
- type
BookingProviderStatusDto:
type: object
properties:
code:
type: string
example: TBO
booking_id:
type: object
example: FL1IMA
nullable: true
booking_code:
type: object
example: REZ6A5A81E9
nullable: true
hotel_confirmation_number:
type: object
example: HCN-482910
nullable: true
hotel_confirmation_status:
type: object
example: Confirmed
nullable: true
hotel_confirmation_note:
type: object
nullable: true
hotel_contact_phone:
type: object
nullable: true
hotel_contact_name:
type: object
nullable: true
raw_status:
type: object
example: SUCCESS
nullable: true
message:
type: object
example: Booking confirmed by supplier.
nullable: true
required:
- code
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: Environment-specific API key created in the Unifystays portal
````