Quickstart

This guide takes you from portal setup to your first hotel search. After this, continue through the booking flow guides.

The current non-production staging/sandbox environment contains only a limited set of places and hotels. It is designed for integration testing and is not a complete production catalogue. Use a destination returned by the environment’s autocomplete endpoint; a production place or hotel ID may not exist there.

1. Configure the Sandbox

Add the credentials for a hotel supplier.
Enable the supplier.
Create a sandbox API key.

Supplier credentials and API keys are managed directly in the portal.

2. Set Your API Key

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

Use the production base URL and a production API key only when you are ready to send live traffic.

3. Find a Destination

curl "$UNIFYSTAYS_BASE_URL/destinations/autocomplete?q=dubai&types=place,hotel&limit=5" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

Use the returned type and matching ID in the search request: hotel_id for a hotel or place_id for a place. See Destination Autocomplete for complete fields, response details, and caching guidance. If your preferred destination is not returned, test with another place available in the environment or contact support to request staging coverage. An empty result for an unavailable destination does not mean your authentication or request format is incorrect.

4. Search Hotels

curl "$UNIFYSTAYS_BASE_URL/hotels/search" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "destination": {
      "type": "place",
      "id": 101
    },
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ],
    "limit": 20,
    "pricing_mode": "instant",
    "sort": "recommended"
  }'

The response includes hotel results and a search_id. When pricing_mode is instant, poll for live supplier prices.

curl "$UNIFYSTAYS_BASE_URL/hotels/search/srch_a1b2c3d4e5f6g7h8/prices" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

Merge data.updated_prices into your visible hotel list using (hotel_id, supplier_code) as the unique quote key. Each quote includes supplier_code and supplier_name. The API returns every supplier price and does not choose which one your UI should display.

5. Continue to Rooms

Pick a hotel from the search response and request room options:

curl "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ]
  }'

The response returns data.sse_stream_url. Connect to it immediately to receive live supplier options:

curl -N "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms/stream/stream_8f4b9d1f6d9e" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

Replace the example path with the exact sse_stream_url returned by your room request. Every provider_options event contains complete bookable options. Each option includes:

booking_token: send the selected option’s token to prebook.
rooms[].room_allocation_id: identifies each exact room slot, including rooms with no static catalogue mapping.
rooms[].provider_room: supplier-room content available for every mapping status, including its name and any supplied images, amenities, bed, and occupancy data.
rooms[].unifystays_room: complete mapped Unifystays room snapshot, or null.
rooms[].occupancy: the adult and child mix that must be assigned during booking.

When rendering a room, use unifystays_room when present; otherwise render provider_room. Keep the option bookable in either case.

6. Prebook the Selected Option

Keep hotel_id from the room request and booking_token from an option on that request’s stream:

curl "$UNIFYSTAYS_BASE_URL/hotels/prebook" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "hotel_id": "123456",
    "booking_token": "bq7.Y0QxTmtKc21Wbmk.3.6zI4D6fUEw2jVv7KQdM4Kw"
  }'

Continue when data.revalidation.decision is READY_TO_BOOK, or after the customer explicitly accepts a RECONFIRMATION_REQUIRED result. Keep data.prebooking_id, data.offer.offer_id, and every room’s room_allocation_id and occupancy for the immediate booking request. unifystays_room may be null; booking identity comes from room_allocation_id.

7. Create the Booking

Send every allocation returned by prebook exactly once. Attach the guests for that room and use one persistent idempotency key for the booking attempt:

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 '{
    "prebooking_id": "pbq7.bjNQb1Y5R2hRWEg.k6jQ3nW4cF1nL4MWvN7A9Q",
    "accepted_offer_id": "off_65db5f20d91b47d3a73d834dfa44c50e",
    "rooms": [
      {
        "room_allocation_id": "ra_2c1fb39ed54742f28d95bd8bc5f4375d",
        "guests": [
          {
            "guest_id": "guest_1",
            "guest_type": "ADULT",
            "is_lead_guest": true,
            "answers": [
              { "requirement_id": "br_title_all_guests_1", "value": "MR" },
              { "requirement_id": "br_first_name_all_guests_2", "value": "Shubham" },
              { "requirement_id": "br_last_name_all_guests_3", "value": "Gupta" },
              { "requirement_id": "br_email_lead_guest_4", "value": "shubham@example.com" },
              { "requirement_id": "br_phone_lead_guest_5", "value": "+919876543210" }
            ]
          },
          {
            "guest_id": "guest_2",
            "guest_type": "ADULT",
            "is_lead_guest": false,
            "answers": [
              { "requirement_id": "br_title_all_guests_1", "value": "MRS" },
              { "requirement_id": "br_first_name_all_guests_2", "value": "Aarohi" },
              { "requirement_id": "br_last_name_all_guests_3", "value": "Gupta" }
            ]
          }
        ]
      }
    ]
  }'

Persist the returned data.booking_id and use it to poll booking status. If a network retry is needed, resend the identical body with the same Idempotency-Key. The requirement IDs above are examples. Always copy the actual IDs from the accepted prebook offer’s booking_requirements; never construct them. Continue with the Hotel Booking Flow or open any endpoint in the API Reference.

Get started

Build your integration

Operate

1. Configure the Sandbox

2. Set Your API Key

3. Find a Destination

4. Search Hotels

5. Continue to Rooms

6. Prebook the Selected Option

7. Create the Booking

​1. Configure the Sandbox

​2. Set Your API Key

​3. Find a Destination

​4. Search Hotels

​5. Continue to Rooms

​6. Prebook the Selected Option

​7. Create the Booking

1. Configure the Sandbox

2. Set Your API Key

3. Find a Destination

4. Search Hotels

5. Continue to Rooms

6. Prebook the Selected Option

7. Create the Booking