KOOB API Documentation

Appearance

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.00,
  "sourceTotalPrice": 1200.00,
  "dmcTotalPriceWithoutPromo": 1300.00,
  "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": "confirmed",
  "secret": "booking-secret-key",
  "bookingRef": "KOOB-2024-123",
  "cancellationFees": 0,
  "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": [
    {
      "id": "room-booking-1",
      "sourceRoomId": "room-source-123",
      "dmcPrice": 240.00,
      "dmcPricePerDay": 240.00,
      "dmcPriceWithoutPromo": 260.00,
      "tags": [
        {
          "label": "Anniversary",
          "start_at": "2024-06-15T00:00:00Z",
          "end_at": "2024-06-20T00:00:00Z"
        }
      ],
      "bedCompositions": [
        {
          "label": "King Bed",
          "quantity": 1
        }
      ],
      "hotelRoom": {
        "displayName": "Deluxe Suite",
        "refundable": "true",
        "mealPlan": "Breakfast Included"
      },
      "travelers": [
        {
          "id": "traveler-1",
          "kind": "adult",
          "gender": "male",
          "firstName": "John",
          "lastName": "Smith",
          "birthdate": "1980-05-15",
          "passportNumber": "P123456789",
          "expirationDate": "2030-12-31",
          "nationality": "US"
        },
        {
          "id": "traveler-2",
          "kind": "adult",
          "gender": "female",
          "firstName": "Jane",
          "lastName": "Smith",
          "birthdate": "1985-08-22",
          "nationality": "US"
        }
      ],
      "promotions": [
        {
          "kind": "percent",
          "promotionKind": "early_bird",
          "value": "10%"
        }
      ]
    }
  ],
  "experiencesBooked": [
    {
      "id": "exp-booking-1",
      "priceWithoutPromo": 300.00,
      "price": 270.00,
      "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"
      }
    }
  ]
}

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": "confirmed",
    "startAt": "2024-06-15",
    "endAt": "2024-06-20",
    "state": "confirmed",
    "totalPrice": 1450.00,
    "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"
  }
]

Booking States ​

Bookings can have different states indicating their current status:

Main States ​

  • draft: Booking is being prepared
  • pending: Awaiting confirmation
  • confirmed: Booking confirmed by supplier
  • pre_confirmed: Conditionally confirmed
  • pending_source: Awaiting external supplier confirmation
  • sent: Booking request sent to supplier
  • refused: Booking declined by supplier
  • canceled: Booking canceled
  • replaced: Booking has been replaced by another

DMC States ​

The dmcState field may differ from the main state and represents the DMC's view of the booking status.

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 Filters ​

  • 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