Create Booking

Create an idempotent hotel booking from a successful Unifystays prebooking response.

POST /hotels/book

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"
          }
        ]
      }
    ]
  }'

200

{
  "success": true,
  "message": "Booking request accepted and is being processed.",
  "data": {
    "booking_id": "ubk_eGQ0dW9uV1Vi",
    "status": "PROCESSING",
    "is_terminal": false,
    "provider": {
      "code": "TBO",
      "booking_id": "FL1IMA",
      "booking_code": "REZ6A5A81E9",
      "hotel_confirmation_number": "HCN-482910",
      "hotel_confirmation_status": "Confirmed",
      "hotel_confirmation_note": {},
      "hotel_contact_phone": {},
      "hotel_contact_name": {},
      "raw_status": "SUCCESS",
      "message": "Booking confirmed by supplier."
    },
    "created_at": "2026-04-15T12:12:11.000Z",
    "updated_at": "2026-04-15T12:12:11.000Z",
    "next_poll_after_ms": 5000,
    "metadata": {}
  }
}

Create a booking only after a successful Prebook a Room response. This endpoint is idempotent and requires an Idempotency-Key header for every request.

Request Example

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 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.

Authorizations

x-api-key · string · header · required

Environment-specific API key created in the Unifystays portal

Headers

Idempotency-Key · string · required

Unique key per booking attempt from client. Reusing the same key with same payload returns the same booking object.

Body

application/json

unifystays_prebooking_id · string · required

Prebooking token from prebook response (data.unifystays_prebooking_id).

Example:

"pbq1.bjNQb1Y5R2hRWEg.k6jQ3nW4cF1nL4MWvN7A9Q"

rooms · object[] · required

Room-wise guest details. Must match prebooking rooms in count and order.

Show child attributes

Response

200

application/json

success · boolean · required

Example:

true

message · string · required

Example:

"Booking request accepted and is being processed."

data · object · required

Show child attributes