Search Bookings

This documentation covers how to retrieve and manage bookings in the KOOB API, including individual booking details, searching through booking lists, and accessing related booking information.

Get Individual Booking

Get Booking by ID

Retrieve detailed information about a specific booking.

Endpoint: GET /api/v1/bookings/{bookingId}

Parameters:

bookingId (path, required): Booking ID

Response:

json

{
  "id": "booking-123",
  "groupUuid": "group-456",
  "groupBookingsIds": ["booking-123", "booking-124"],
  "startAt": "2024-06-15",
  "endAt": "2024-06-20",
  "createdAt": "2024-05-01T10:00:00Z",
  "updatedAt": "2024-05-15T14:30:00Z",
  "currency": "EUR",
  "roomTotalPrices": "1200.00",
  "totalPrice": 1450.0,
  "sourceTotalPrice": 1200.0,
  "dmcTotalPriceWithoutPromo": 1300.0,
  "cancellationFees": 0,
  "customerLastName": "Smith",
  "customerFirstName": "John",
  "customerCity": "Paris",
  "customerZipCode": "75001",
  "customerAddress": "123 Rue de Rivoli",
  "customerAdditionalAddress": "Apartment 4B",
  "customerCompany": "Travel Corp",
  "customerEmail": "john.smith@email.com",
  "customerPhoneNumber": "+33123456789",
  "customerInternalReference": "TC-2024-001",
  "customerFileId": "file-456",
  "kind": "hotel",
  "showToTa": true,
  "note": "Late check-in requested",
  "operatorTourName": "Paris Discovery Tour",
  "networkName": "Hotel Network",
  "dmcReference": "DMC-2024-789",
  "toReference": "TO-2024-456",
  "comment": "VIP client - ensure smooth check-in",
  "canceledAt": null,
  "state": "confirmed",
  "dmcState": "instant_booking",
  "secret": "booking-secret-key",
  "bookingRef": "KOOB-2024-123",
  "guaranteedDeparture": "true",
  "lang": "en",
  "hotelConfirmationNumber": "HTL-CONF-789",
  "supplierCode": "SUPPLIER-123",
  "numberOfNights": 5,
  "hotelKeeperMessage": "Welcome! Your room is ready.",
  "hotelKeeperMessageSendAt": "2024-06-14T16:00:00Z",
  "allotmentAvailable": true,
  "hotel": {
    "id": "hotel-456",
    "displayName": "Grand Hotel Paris",
    "stars": 5,
    "address": "123 Champs-Élysées, Paris",
    "cityName": "Paris",
    "regionName": "Île-de-France",
    "countryName": "France",
    "currency": "EUR",
    "showToTa": true,
    "hasToRequest": false,
    "canBeBooked": true,
    "state": "available"
  },
  "organization": {
    "id": "org-789",
    "displayName": "Luxury Hotels Group",
    "avatarUrl": "https://example.com/org-logo.jpg",
    "bookingReceptionEmail": "bookings@luxuryhotels.com",
    "scope": "dmc"
  },
  "user": {
    "id": "user-123",
    "firstName": "Alice",
    "lastName": "Johnson"
  },
  "trip": {
    "id": "trip-789",
    "name": "Paris Summer Vacation",
    "startDate": "2024-06-15",
    "endDate": "2024-06-20"
  },
  "roomsBooked": [
    {
      "room": {
        "id": "Um9vbUNvbXBvc2l0aW9uOjE=",
        "hotelRoomId": "SG90ZWxSb29tOjc3",
        "name": "Deluxe Suite",
        "otherProposal": false,
        "bedChoice": {
          "id": "SG90ZWxSb29tQ29tcG9zaXRpb246MzE=",
          "name": "King bed (1)",
          "currency": "EUR",
          "totalPriceWithoutPromo": 1300.0,
          "totalPriceWithPromo": 1200.0,
          "pricePerDay": 240.0,
          "contractingConditions": "Rooms are held until 18:00 local time.",
          "checkInInstructions": "Check-in from 14:00 at the main lobby.",
          "hotelFees": [],
          "cancelConditions": [
            {
              "deduction": 240.0,
              "refundable": true,
              "startAt": "2024-06-01 00:00:00 UTC",
              "endAt": "2024-06-12 23:59:59 UTC"
            },
            {
              "deduction": 1200.0,
              "refundable": false,
              "startAt": "2024-06-13 00:00:00 UTC",
              "endAt": "2024-06-15 23:59:59 UTC"
            }
          ],
          "promotions": ["Early booking -10%"],
          "tags": []
        }
      },
      "travelers": [
        {
          "id": "traveler-1",
          "kind": "adult",
          "gender": "male",
          "firstName": "John",
          "lastName": "Smith",
          "birthdate": "1980-05-15",
          "nationality": "US"
        },
        {
          "id": "traveler-2",
          "kind": "adult",
          "gender": "female",
          "firstName": "Jane",
          "lastName": "Smith",
          "birthdate": "1985-08-22",
          "nationality": "US"
        }
      ]
    }
  ],
  "experiencesBooked": [
    {
      "id": "exp-booking-1",
      "priceWithoutPromo": 300.0,
      "price": 270.0,
      "promotions": ["Group Discount 10%"],
      "extras": "Audio guide included",
      "travelers": [
        {
          "id": "traveler-1",
          "firstName": "John",
          "lastName": "Smith",
          "kind": "adult"
        }
      ],
      "experience": {
        "id": "exp-456",
        "name": "Louvre Museum Private Tour",
        "organizationName": "Paris Culture Tours"
      }
    }
  ]
}

Cancellation conditions. Each booked room keeps the fee windows it was booked under in room.bedChoice.cancelConditions, ordered by time: cancelling inside a window costs its deduction, in the bed choice currency; refundable: false marks a window whose deduction is the full price. On v1 and v2, startAt and endAt are UTC timestamps in the format YYYY-MM-DD HH:mm:ss UTC (e.g. 2024-06-12 23:59:59 UTC). This is the only field family that does not use ISO 8601; the v3 endpoints send ISO 8601 throughout.

Search and Filter Bookings

Get Booking List

Search and filter bookings based on various criteria.

Endpoint: POST /api/v1/bookings/list

Request Body:

json

{
  "rangeDates": {
    "from": "2024-06-01",
    "to": "2024-06-30"
  },
  "search": "Smith",
  "kind": "hotel",
  "rangeDatesTravelPeriod": {
    "from": "2024-06-15",
    "to": "2024-06-20"
  },
  "product": "hotel",
  "scope": "dmc",
  "startAt": "2024-06-15",
  "endAt": "2024-06-20",
  "withReplacedBookings": false,
  "organizationId": "org-789",
  "column": "createdAt",
  "stars": "5",
  "customerFileId": "file-456",
  "hotelId": "hotel-456",
  "experienceId": "exp-456"
}

Response:

json

[
  {
    "id": "booking-123",
    "bookingId": "booking-123",
    "koobId": 123456,
    "allotmentAvailable": true,
    "customerFirstName": "John",
    "customerLastName": "Smith",
    "customerInternalReference": "TC-2024-001",
    "dmcReference": "DMC-2024-789",
    "toReference": "TO-2024-456",
    "supplierCode": "SUPPLIER-123",
    "currency": "EUR",
    "createdAt": "2024-05-01T10:00:00Z",
    "dmcState": "instant_booking",
    "startAt": "2024-06-15",
    "endAt": "2024-06-20",
    "state": "confirmed",
    "totalPrice": 1450.0,
    "guaranteedDeparture": true,
    "kind": "hotel",
    "numberOfNights": 5,
    "experienceCompositions": null,
    "roomCompositions": [
      {
        "id": "room-comp-1",
        "travelers": [
          {
            "id": "traveler-1",
            "firstName": "John",
            "lastName": "Smith"
          }
        ]
      }
    ],
    "hotel": {
      "id": "hotel-456",
      "displayName": "Grand Hotel Paris"
    },
    "user": {
      "id": "user-123",
      "firstName": "Alice",
      "lastName": "Johnson"
    }
  }
]

Additional Booking Information

Get Booking Documents

Retrieve documents associated with a booking.

Endpoint: GET /api/v1/bookings/{bookingId}/documents

Response:

json

[
  {
    "id": "doc-123",
    "fileName": "booking-confirmation.pdf",
    "fileType": "application/pdf",
    "uploadedAt": "2024-05-01T10:30:00Z",
    "downloadUrl": "https://api.koob.tech/documents/doc-123/download"
  },
  {
    "id": "doc-124",
    "fileName": "hotel-voucher.pdf",
    "fileType": "application/pdf",
    "uploadedAt": "2024-05-01T10:35:00Z",
    "downloadUrl": "https://api.koob.tech/documents/doc-124/download"
  }
]

Get Booking Messages

Retrieve messages and communications related to a booking.

Endpoint: GET /api/v1/bookings/{bookingId}/messages

Response:

json

[
  {
    "id": "msg-123",
    "sender": {
      "id": "user-456",
      "firstName": "Hotel",
      "lastName": "Manager"
    },
    "message": "Your room has been upgraded to a suite at no extra charge.",
    "sentAt": "2024-06-14T16:00:00Z",
    "messageType": "update"
  },
  {
    "id": "msg-124",
    "sender": {
      "id": "user-123",
      "firstName": "Alice",
      "lastName": "Johnson"
    },
    "message": "Customer requesting late check-in at 8 PM",
    "sentAt": "2024-06-14T14:30:00Z",
    "messageType": "request"
  }
]

Cancel a Booking

Cancel an existing booking.

Endpoint: DELETE /api/v1/bookings/{bookingId}

Request Body:

Field	Required	Description
`reason`	yes	Free-text cancellation reason, stored in the booking history.

Response: 200 with an empty body. The booking moves to state canceled.

Cancellation fees follow the cancellation conditions of the rate you booked (shown at availability time and in the booking's contract text): cancelling inside a penalty window sets cancellationFees on the booking. Cancellation is permanent — to change dates or rooms instead, create a replacement booking (replaceBookingId on the book endpoints) and cancel the old one.

Booking States

state is the lifecycle of the booking. Which state a new booking starts in depends on the rate: instantly-bookable rates confirm immediately; on-request rates wait for the supplier.

`state`	Meaning	What happens next
`draft`	Being prepared, not yet submitted.	Submitted or discarded.
`pending`	The hotel answered with a counter-proposal (other room, dates or price); the DMC must accept or refuse it.	Becomes `sent` again, `confirmed` or `refused`.
`sent`	On-request booking waiting for the hotel's answer.	Becomes `confirmed`, `refused` or `pending`.
`pending_source`	Awaiting confirmation from an external supplier system.	Becomes `confirmed` or `refused`.
`pre_confirmed`	Conditionally confirmed, pending final confirmation.	Becomes `confirmed` or `refused`.
`confirmed`	Active, confirmed booking.	Stays confirmed unless cancelled or replaced.
`refused`	Declined by the supplier. Final.	—
`canceled`	Cancelled. Final.	—
`replaced`	Superseded by a replacement booking. Final.	The replacing booking carries the stay.
`failure`	The booking write failed at the supplier. Final.	Contact support with the booking ID.

Treat refused, canceled, replaced and failure as terminal; everything else can still move. Poll GET /api/v3/bookings/{id} (or GET /api/v1/bookings/{bookingId}, or watch the booking history) to track on-request confirmations.

An on-request booking stays sent until the hotel or the DMC answers. When the booking was made more than 14 days before check-in and is still unanswered 7 days before check-in, the platform reminds the hotel once. If nobody has answered when check-in is 24 hours away or less, the platform refuses it automatically (state: refused, hotel message "Automatically refused: the hotel did not answer before check-in."), so every on-request booking reaches a terminal state before the stay. If you need an answer earlier, cancel the booking with DELETE /api/v1/bookings/{bookingId} and treat it as refused.

`dmcState`

dmcState is not a second status — it records how the booking was made:

instant_booking: booked against instantly-available inventory; confirmed at creation.
on_request: needs supplier confirmation; follow state for the outcome.

dmcState is set once at booking time and never changes afterwards.

Booking Messages and Documents

Each booking carries a message thread and a document store shared between you and the supplier:

PUT /api/v1/bookings/{bookingId}/messages — post a message: { "message": "..." }.
GET /api/v1/bookings/{bookingId}/messages — read the thread (see example above).
PUT /api/v1/bookings/{bookingId}/documents — attach a document (multipart upload).
GET /api/v1/bookings/{bookingId}/documents — list documents; download one with GET /api/v1/bookings/{bookingId}/documents/{documentId}.

Filtering Options

Date Range Filters

rangeDates: Filter by booking creation dates
rangeDatesTravelPeriod: Filter by travel/stay dates
startAt/endAt: Specific travel start/end dates

product: Filter by product type (hotel, experience)
kind: Specific booking kind
hotelId: Filter by specific hotel
experienceId: Filter by specific experience

Organization Filters

scope: Filter by organization scope (dmc, to)
organizationId: Filter by specific organization

Customer Filters

search: Search in customer names and references
customerFileId: Filter by customer file
stars: Filter hotel bookings by star rating

Search Bookings ​

Get Individual Booking ​

Get Booking by ID ​

Search and Filter Bookings ​

Get Booking List ​

Additional Booking Information ​

Get Booking Documents ​

Get Booking Messages ​

Cancel a Booking ​

Booking States ​

dmcState ​

Booking Messages and Documents ​

Filtering Options ​

Date Range Filters ​

Product Filters ​

Organization Filters ​

Customer Filters ​

Search Bookings

Get Individual Booking

Get Booking by ID

Search and Filter Bookings

Get Booking List

Additional Booking Information

Get Booking Documents

Get Booking Messages

Cancel a Booking

Booking States

`dmcState`

Booking Messages and Documents

Filtering Options

Date Range Filters

Product Filters

Organization Filters

Customer Filters