List Bookings

curl "$UNIFYSTAYS_BASE_URL/hotels/book?status=CONFIRMED&page=1&limit=20" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

{
  "contract_version": "1",
  "success": true,
  "message": "Bookings fetched successfully.",
  "data": {
    "items": [
      {
        "booking_id": "ubk_eGQ0dW9uV1Vi",
        "status": "CONFIRMED",
        "is_terminal": true,
        "hotel": {
          "hotel_id": "13553916",
          "hotel_name": "Ramada Plaza by Wyndham Dubai Deira",
          "city": "Dubai",
          "country": "United Arab Emirates",
          "stars": 4
        },
        "check_in": "2026-05-26",
        "check_out": "2026-05-28",
        "nights": 2,
        "rooms_count": 1,
        "guests_count": 2,
        "adults_count": 2,
        "children_count": 0,
        "supplier_total": {
          "amount_minor": 17700,
          "currency": "USD",
          "currency_exponent": 2
        },
        "provider_code": "TRIPJACK",
        "provider_booking_id": "TJ202487947162",
        "provider_booking_code": "REZ6A5A81E9",
        "hotel_confirmation_number": "HCN-482910",
        "hotel_confirmation_status": "Confirmed",
        "failure_code": {},
        "failure_message": {},
        "created_at": "2026-04-15T12:12:11.000Z",
        "updated_at": "2026-04-15T12:12:11.000Z",
        "completed_at": "2026-04-15T12:15:11.000Z"
      }
    ],
    "meta": {
      "total": 137,
      "page": 1,
      "limit": 20,
      "totalPages": 7,
      "hasNextPage": true,
      "hasPrevPage": false
    },
    "summary": {
      "total": 137,
      "countsByStatus": {
        "CONFIRMED": 110,
        "PROCESSING": 3,
        "ON_HOLD": 2,
        "FAILED": 15,
        "CANCELLATION_PENDING": 1,
        "CANCELLED": 6
      }
    }
  }
}

GET

hotels

book

curl "$UNIFYSTAYS_BASE_URL/hotels/book?status=CONFIRMED&page=1&limit=20" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

{
  "contract_version": "1",
  "success": true,
  "message": "Bookings fetched successfully.",
  "data": {
    "items": [
      {
        "booking_id": "ubk_eGQ0dW9uV1Vi",
        "status": "CONFIRMED",
        "is_terminal": true,
        "hotel": {
          "hotel_id": "13553916",
          "hotel_name": "Ramada Plaza by Wyndham Dubai Deira",
          "city": "Dubai",
          "country": "United Arab Emirates",
          "stars": 4
        },
        "check_in": "2026-05-26",
        "check_out": "2026-05-28",
        "nights": 2,
        "rooms_count": 1,
        "guests_count": 2,
        "adults_count": 2,
        "children_count": 0,
        "supplier_total": {
          "amount_minor": 17700,
          "currency": "USD",
          "currency_exponent": 2
        },
        "provider_code": "TRIPJACK",
        "provider_booking_id": "TJ202487947162",
        "provider_booking_code": "REZ6A5A81E9",
        "hotel_confirmation_number": "HCN-482910",
        "hotel_confirmation_status": "Confirmed",
        "failure_code": {},
        "failure_message": {},
        "created_at": "2026-04-15T12:12:11.000Z",
        "updated_at": "2026-04-15T12:12:11.000Z",
        "completed_at": "2026-04-15T12:15:11.000Z"
      }
    ],
    "meta": {
      "total": 137,
      "page": 1,
      "limit": 20,
      "totalPages": 7,
      "hasNextPage": true,
      "hasPrevPage": false
    },
    "summary": {
      "total": 137,
      "countsByStatus": {
        "CONFIRMED": 110,
        "PROCESSING": 3,
        "ON_HOLD": 2,
        "FAILED": 15,
        "CANCELLATION_PENDING": 1,
        "CANCELLED": 6
      }
    }
  }
}

Use this endpoint for booking history, operational views, customer service, and finance reconciliation. It returns paginated bookings belonging to the current organization.

Request Example

curl "$UNIFYSTAYS_BASE_URL/hotels/book?status=CONFIRMED&page=1&limit=20" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en"

Filter and Sort

The API supports free-text search across booking identifiers and hotel context, along with filters for:

Booking status and terminal state.
Hotel, city, and provider.
Stay dates and booking creation dates.
Sort field, sort direction, page, and limit.

Use the returned data.meta for pagination and data.summary for aggregate counts. For one booking’s current state, call Get Booking Status. For a full itinerary or support record, call Get Booking Details.

A list result is ideal for dashboards and support screens. Do not use a cached list row as the final truth for a booking that is currently processing or being cancelled; retrieve its latest status instead.

The OpenAPI section below provides the complete filtering, sorting, pagination, and response field reference.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

X-Unifystays-Contract-Version

enum<string>

default:1

Hotel API contract version. Missing defaults to v1.

Available options:

1

Query Parameters

string

Free-text search across booking ids/codes, HCN, hotel name, city, and country (case-insensitive).

Example:

"ubk_"

status

enum<string>[]

Filter by status. Accepts repeated values or CSV, e.g. status=CONFIRMED&status=ON_HOLD or status=CONFIRMED,ON_HOLD.

Available options:

AWAITING_REVIEW,

PROCESSING,

CONFIRMED,

ON_HOLD,

FAILED,

CANCELLATION_PENDING,

CANCELLED

Example:

["CONFIRMED", "PROCESSING"]

hotel_id

string

Filter by hotel id.

Example:

"13553916"

city

string

Filter by city (case-insensitive exact).

Example:

"Dubai"

provider_code

string

Filter by provider code.

Example:

"TRIPJACK"

check_in_from

string

Check-in date >= (YYYY-MM-DD).

Example:

"2026-05-01"

check_in_to

string

Check-in date <= (YYYY-MM-DD).

Example:

"2026-05-31"

created_from

string

Created date >= (ISO 8601).

Example:

"2026-04-01T00:00:00Z"

created_to

string

Created date <= (ISO 8601).

Example:

"2026-04-30T23:59:59Z"

is_terminal

boolean

Only return terminal (true) or non-terminal (false) bookings.

Example:

false

sort_by

enum<string>

default:created_at

Field to sort by.

Available options:

created_at,

check_in,

check_out,

supplier_total,

status

sort_order

enum<string>

default:DESC

Sort direction.

Available options:

ASC,

DESC

page

number

default:1

Page number (1-based).

Required range: x >= 1

Example:

1

limit

number

default:20

Results per page.

Required range: 1 <= x <= 100

Example:

20

Response

contract_version

string

required

Example:

"1"

success

boolean

required

Example:

true

message

string

required

Example:

"Bookings fetched successfully."

data

object

required

Show child attributes

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

Request Example

Filter and Sort

Authorizations

Headers

Query Parameters

Response

​Request Example

​Filter and Sort

Authorizations

Headers

Query Parameters

Response

Request Example

Filter and Sort