KOOB API Documentation

Appearance

Experience Booking ​

Create Experience Booking ​

Book experiences, activities, transfers, or programs with specified details and traveler information.

TIP

You can book multiple experiences in a single request by providing an array of booking objects.

Endpoint: POST /api/v1/experiences/book

Request Body:

json
[
  {
    "id": "booking-456",
    "groupUuid": "group-789",
    "hasChangedHotels": "false",
    "replaceBookingId": "old-booking-123",
    "adminBookingId": "admin-789",
    "tripId": "trip-456",
    "startAt": "2024-06-15",
    "endAt": "2024-06-15",
    "customerLastName": "Smith",
    "customerFirstName": "John",
    "customerCity": "Paris",
    "customerZipCode": "75001",
    "customerAddress": "123 Rue de Rivoli",
    "customerAdditionalAddress": "Apartment 4B",
    "customerCompany": "Travel Corp",
    "customerInternalReference": "TC-2024-001",
    "customerFileId": "file-456",
    "customerEmail": "john.smith@email.com",
    "customerPhoneNumber": "+33123456789",
    "tourOperatorName": "Paris Tours",
    "networkName": "Experience Network",
    "note": "Client prefers morning tours",
    "travelers": [
      {
        "id": "traveler-1",
        "kind": "adult",
        "gender": "male",
        "firstName": "John",
        "lastName": "Smith",
        "nationality": "US",
        "passportNumber": "P123456789",
        "expirationDate": "2030-12-31T00:00:00Z",
        "birthdate": "1980-05-15T00:00:00Z",
        "ageIsExact": true
      },
      {
        "id": "traveler-2",
        "kind": "adult",
        "gender": "female",
        "firstName": "Jane",
        "lastName": "Smith",
        "nationality": "US",
        "passportNumber": "P987654321",
        "expirationDate": "2030-12-31T00:00:00Z",
        "birthdate": "1985-08-22T00:00:00Z",
        "ageIsExact": true
      },
      {
        "id": "traveler-3",
        "kind": "child",
        "gender": "male",
        "firstName": "Tommy",
        "lastName": "Smith",
        "nationality": "US",
        "birthdate": "2010-05-15T00:00:00Z",
        "ageIsExact": true
      }
    ],
    "selectedHotels": [
      {
        "hotelId": "hotel-123",
        "bookedOnMyOwn": false,
        "programId": "program-456"
      }
    ],
    "extras": [
      {
        "id": "extra-1",
        "adultCount": 2,
        "dayIndex": 1,
        "childrenBirthdates": ["2010-05-15"],
        "scope": "day",
        "cancelConditions": {
          "text": "Non-refundable"
        },
        "isIncluded": "false"
      }
    ],
    "adults": 2,
    "childrenBirthdates": ["2010-05-15"]
  }
]

Response:

json
[
  {
    "id": "booking-789",
    "groupUuid": "group-789",
    "startAt": "2024-06-15",
    "endAt": "2024-06-15",
    "createdAt": "2024-05-01T10:00:00Z",
    "updatedAt": "2024-05-01T10:00:00Z",
    "currency": "EUR",
    "customerLastName": "Smith",
    "customerFirstName": "John",
    "customerEmail": "john.smith@email.com",
    "state": "pending",
    "dmcState": "pending",
    "totalPrice": 450.00,
    "experiencesBooked": [
      {
        "id": "exp-booking-1",
        "priceWithoutPromo": 500.00,
        "price": 450.00,
        "promotions": ["Early Bird 10%"],
        "extras": "Audio guide upgrade",
        "travelers": [
          {
            "id": "traveler-1",
            "firstName": "John",
            "lastName": "Smith",
            "kind": "adult"
          }
        ],
        "experience": {
          "id": "exp-123",
          "name": "Louvre Museum Private Tour",
          "organizationName": "Paris Culture Tours"
        }
      }
    ]
  }
]

Update Experience Booking ​

Update an existing experience booking with new options or modifications.

Endpoint: PATCH /api/v1/experiences/updatedBook/{adminBookingId}

Parameters:

  • adminBookingId (path, required): Admin booking ID

Request Body:

json
{
  "filters": {
    "search": "Updated preferences",
    "themes": ["cultural", "adventure"]
  },
  "extras": [
    {
      "id": "extra-2",
      "adultCount": 2,
      "dayIndex": 1,
      "childrenBirthdates": ["2010-05-15"],
      "scope": "global",
      "isIncluded": "true"
    }
  ]
}

Experience Composition Extras ​

Update Experience Extra ​

Update details of an experience composition extra.

Endpoint: PUT /api/v1/experiences/extras/{experienceCompositionExtraId}

Parameters:

  • experienceCompositionExtraId (path, required): Experience composition extra ID

Request Body:

json
{
  "id": "extra-1",
  "extra": {
    "id": "exp-extra-123",
    "name": "Audio Guide Upgrade"
  },
  "state": "confirmed",
  "price": 25.00,
  "priceWithoutPromo": 30.00,
  "extraCompositionId": "comp-456",
  "adultPax": 2,
  "childrenBirthdates": ["2010-05-15"],
  "dayIndex": 1
}

Cancel Experience Extra ​

Cancel an experience composition extra.

Endpoint: DELETE /api/v1/experiences/extras/{experienceCompositionExtraId}

Parameters:

  • experienceCompositionExtraId (path, required): Experience composition extra ID

Booking Management ​

Get Experience Organizations ​

Get organizations linked to a specific experience.

Endpoint: GET /api/v1/experiences/{experienceId}/organizations

Parameters:

  • experienceId (path, required): Experience ID

Response:

json
[
  {
    "id": "org-123",
    "displayName": "Paris Culture Tours"
  },
  {
    "id": "org-456", 
    "displayName": "Seine River Cruises"
  }
]

Export Experience ​

Export experience details in various formats.

Endpoint: POST /api/v1/experiences/{experienceId}/export/{exportFormat}

Parameters:

  • experienceId (path, required): Experience ID
  • exportFormat (path, required): Export format (e.g., "pdf", "excel")
  • locale (query, optional): 2-letter language code

Request Body:

json
{
  "startAt": "2024-06-15",
  "endAt": "2024-06-15",
  "adults": 2,
  "children": 1,
  "price": 450.00,
  "currency": "EUR",
  "extras": [
    {
      "name": "Audio Guide",
      "adults": 2,
      "children": 1,
      "price": 25.00,
      "currency": "EUR"
    }
  ],
  "clientFolderReference": "TC-2024-001",
  "clientFolderId": "folder-456"
}

Response:

json
{
  "downloadUrl": "https://example.com/exports/experience-export.pdf",
  "expiresAt": "2024-06-10T12:00:00Z"
}

Please refer to the bookings documentation for more details on retrieving and managing bookings.