Skip to main content

BookResponse

Result of the booking.

statusstringrequired

completed, pending, failed or unknown (the provider did not answer in time after receiving the request: a booking may exist; re-send the identical request later).

Example: completed
supplier_booking_idstring | nullnullable

Provider booking id.

Example: 01aa00bb11cc22dd33ee44ff55667781
supplier_booking_refstring | nullnullable

Provider confirmation number. Show it to the customer.

Example: PRV0000001
supplier_reference object

Store it unchanged and send it to booking details and cancel. Empty ({}) when no booking was made (failed, unknown).

booking_id object

Provider booking id.

anyOf
string
Example: healthy
confirmation_number object

Provider confirmation number.

anyOf
string
Example: healthy
provider object

Provider.

anyOf
string
Example: healthy
booking_status object

Book status at book time (completed, pending).

anyOf
string
Example: healthy
booking_tokenstringrequired

Opaque, encrypted state of the booking, tied to your API key. Required by booking-details and cancel; a modified token or booking_id is rejected with 422 invalid_booking_token.

Example: bt1.gAAAAAB...opaque-booking-token...(about 1-2 kB; trimmed in this example)
property name*any

Store it unchanged and send it to booking details and cancel. Empty ({}) when no booking was made (failed, unknown).

Example: {"booking_id":"01aa00bb11cc22dd33ee44ff55667781","confirmation_number":"PRV0000001","provider":"provider_a","booking_status":"completed","booking_token":"bt1.gAAAAAB...opaque-booking-token...(about 1-2 kB; trimmed in this example)"}
total_pricenumber | nullnullable

Booked price, in the currency of the search.

Example: 2509.96
currencystring | nullnullable

Currency of total_price: the search's currency.

Example: INR
booking_details object

The booking at book time, in the booking-details shape. Empty when no booking was made.

anyOf

Normalised booking, the same shape for every provider. Every key is present; unknown values are null.

details_versionstringrequired

Version of this structure: "3".

Example: 3
booking objectrequired

Booking identity and status.

tp_booking_ref objectrequired

Your internal_reference.

anyOf
string
Example: healthy
provider objectrequired

Provider.

anyOf
string
Example: healthy
supplier_booking_id objectrequired

Provider booking id.

anyOf
string
Example: healthy
supplier_confirmation_number objectrequired

Provider confirmation number. Show it on the voucher.

anyOf
string
Example: healthy
statusstringrequired

Booking status.

Possible values: [confirmed, pending, cancellation_pending, cancelled, failed, unknown]

Example: confirmed
status_sourcestring | nullnullablerequired

supplier: live provider lookup. book_reference: status recorded at book time. null when status is unknown.

Possible values: [supplier, book_reference]

Example: book_reference
supplier_status objectrequired

Provider's own status word.

anyOf
string
Example: healthy
booked_at objectrequired

Booking time, ISO 8601 UTC.

anyOf
string
Example: healthy
trip objectrequired

The ride.

transfer_type objectrequired

airport, point_to_point or hourly.

anyOf
string
Example: healthy
direction objectrequired

arrival, departure, outbound, return or round_trip.

anyOf
string
Example: healthy
pickup objectrequired

A pickup or drop-off location.

typestring | nullnullablerequired

airport or address.

Possible values: [airport, address]

Example: airport
iata objectrequired

Airport IATA code.

anyOf
string
Example: healthy
name objectrequired

Place or airport name.

anyOf
string
Example: healthy
terminal objectrequired

Terminal.

anyOf
string
Example: healthy
address objectrequired

Address.

anyOf
string
Example: healthy
latnumber | nullnullablerequired

Latitude.

Example: 18.9217
lngnumber | nullnullablerequired

Longitude.

Example: 72.8332
dropoff objectrequired

A pickup or drop-off location.

typestring | nullnullablerequired

airport or address.

Possible values: [airport, address]

Example: airport
iata objectrequired

Airport IATA code.

anyOf
string
Example: healthy
name objectrequired

Place or airport name.

anyOf
string
Example: healthy
terminal objectrequired

Terminal.

anyOf
string
Example: healthy
address objectrequired

Address.

anyOf
string
Example: healthy
latnumber | nullnullablerequired

Latitude.

Example: 18.9217
lngnumber | nullnullablerequired

Longitude.

Example: 72.8332
pickup_datetime objectrequired

Pickup, ISO 8601 local time with offset when known.

anyOf
string
Example: healthy
timezone objectrequired

IANA time zone of the pickup.

anyOf
string
Example: healthy
flight objectrequired

Flight.

airline objectrequired

Airline.

anyOf
string
Example: healthy
number objectrequired

Flight number.

anyOf
string
Example: healthy
terminalstring | nullnullablerequired

Terminal.

Example: healthy
datetime objectrequired

Flight time, local.

anyOf
string
Example: healthy
return_datetimestring | nullnullablerequired

Return pickup, for a round trip booked as one leg.

Example: healthy
hoursnumber | nullnullablerequired

Booked hours (hourly hire).

Example: 4
locations_sourcestring | nullnullablerequired

Where the addresses come from.

Possible values: [supplier, book_snapshot, mixed]

Example: book_snapshot
route_matches_bookingboolean | nullnullablerequired

false: the provider's route differs from what was booked. null: not comparable.

Example: true
passengers objectrequired

Passengers.

lead objectrequired

Lead passenger.

name objectrequired

Name.

anyOf
string
Example: healthy
email objectrequired

Email.

anyOf
string
Example: healthy
phone objectrequired

Phone.

anyOf
string
Example: healthy
adultsinteger | nullnullablerequired

Adults.

Example: 2
childreninteger | nullnullablerequired

Children.

Example: 0
infantsinteger | nullnullablerequired

Infants.

Example: 0
totalinteger | nullnullablerequired

Total passengers.

Example: 2
vehicle objectrequired

Vehicle.

category objectrequired

Provider's category, free text.

anyOf
string
Example: healthy
model objectrequired

Example model.

anyOf
string
Example: healthy
or_similarbooleanrequired

Always true.

Example: true
max_passengersinteger | nullnullablerequired

Seats.

Example: 3
max_bagsinteger | nullnullablerequired

Suitcases.

Example: 3
countinteger | nullnullablerequired

Number of vehicles.

Example: 1
image_url objectrequired

Picture.

anyOf
string
Example: healthy
service objectrequired

Service and meeting the driver.

type objectrequired

Provider's service type.

anyOf
string
Example: healthy
duration_minutesinteger | nullnullablerequired

Ride time, or booked duration (hourly).

Example: 45
meet_and_greetboolean | nullnullablerequired

Driver waits inside with a name sign.

Example: false
free_waiting_minutesinteger | nullnullablerequired

Waiting time included.

Example: 33
meeting_point objectrequired

Where to meet the driver.

anyOf
string
Example: healthy
pickup_instructions objectrequired

Provider instructions for the passenger; multi-line.

anyOf
string
Example: healthy
child_seatsinteger | nullnullablerequired

Child seats booked.

Example: 0
booster_seatsinteger | nullnullablerequired

Booster seats booked.

Example: 0
pin_to_start_ridestring | nullnullablerequired

Code the passenger gives the driver.

Example: healthy
package objectrequired

Package included.

hours_includednumber | nullnullablerequired

Hours.

Example: 4
km_includednumber | nullnullablerequired

Kilometres.

Example: 100
daysinteger | nullnullablerequired

Days.

codestring | nullnullablerequired

Package code.

Example: healthy
labelstring | nullnullablerequired

Label.

Example: healthy
extra_charges objectrequired

Charges beyond the package.

extra_km_rate objectrequired

Per extra km.

anyOf

An amount in the requested currency.

amountnumberrequired

Amount.

Example: 18
currencystringrequired

ISO 4217 currency: the requested currency.

Example: INR
extra_hour_rate objectrequired

Per extra hour.

anyOf

An amount in the requested currency.

amountnumberrequired

Amount.

Example: 18
currencystringrequired

ISO 4217 currency: the requested currency.

Example: INR
night_charge objectrequired

Night charge.

anyOf

An amount in the requested currency.

amountnumberrequired

Amount.

Example: 18
currencystringrequired

ISO 4217 currency: the requested currency.

Example: INR
driver_allowance objectrequired

Driver allowance.

anyOf

An amount in the requested currency.

amountnumberrequired

Amount.

Example: 18
currencystringrequired

ISO 4217 currency: the requested currency.

Example: INR
driver objectrequired

Driver; usually known shortly before pickup.

namestring | nullnullablerequired

Name.

Example: healthy
phonestring | nullnullablerequired

Phone.

Example: healthy
photo_urlstring | nullnullablerequired

Photo.

Example: healthy
vehicle_platestring | nullnullablerequired

Number plate.

Example: healthy
supplier_contact objectrequired

Provider customer contact.

name objectrequired

Name.

anyOf
string
Example: healthy
phone objectrequired

Phone.

anyOf
string
Example: healthy
email objectrequired

Email.

anyOf
string
Example: healthy
support_phone objectrequired

Support phone.

anyOf
string
Example: healthy
price objectrequired

Price.

totalnumber | nullnullablerequired

Booked price.

Example: 2509.96
currency objectrequired

ISO 4217.

anyOf
string
Example: healthy
paidnumber | nullnullablerequired

Amount in the booking currency (the search's currency), when the provider reports it.

Example: 2509.96
cancellation objectrequired

Cancellation terms and outcome.

free_cancellation_until objectrequired

Last moment for free cancellation, ISO 8601 (local with offset when known).

anyOf
string
Example: healthy
free_cancellation_hoursnumber | nullnullablerequired

Free cancellation up to this many hours before pickup.

Example: 0
policy_text objectrequired

Policy in words.

anyOf
string
Example: healthy
rules object[]required

Refund steps.

  • Array [
    • hours_before_pickupnumberrequired

    Hours before pickup.

    Example: 4
    refund_percentnumberrequired

    Refund in percent of the price.

    Example: 100
  • ]
    • cancelledbooleanrequired

    true once cancelled.

    Example: false
    cancelled_at objectrequired

    Cancellation time, ISO 8601 UTC.

    anyOf
    string
    Example: healthy
    refund_amountnumber | nullnullablerequired

    Refund.

    Example: 400
    refund_currency objectrequired

    Refund currency.

    anyOf
    string
    Example: healthy
    refund_sourcestring | nullnullablerequired

    Origin of the refund amount.

    Possible values: [supplier, policy_estimate]

    Example: policy_estimate
    cancelled_at_sourcestring | nullnullablerequired

    Origin of cancelled_at.

    Possible values: [supplier, tp_cancel]

    Example: tp_cancel
    supplier_voucher_url objectrequired

    Provider's own voucher page, when offered.

    anyOf
    string
    Example: healthy
    error object

    Set when status is failed or unknown.

    anyOf

    Why a recheck, book, booking-details or cancel did not succeed.

    codestringrequired

    recheck_failed, recheck_error, unavailable, currency_unavailable, book_failed, book_error, book_outcome_unknown, booking_details_failed, booking_details_error, cancel_failed, cancel_error or cancel_outcome_unknown. New codes may be added.

    Example: book_outcome_unknown
    messagestringrequired

    Explanation, often with the provider's reason. Do not parse.

    Example: The booking outcome could not be confirmed with the provider. Do not book again: retry the same request (same internal_reference) later, or contact support w...
    providerstring | nullnullable

    Provider.

    Example: provider_a
    BookResponse
    {
      "status": "completed",
      "supplier_booking_id": "01aa00bb11cc22dd33ee44ff55667781",
      "supplier_booking_ref": "PRV0000001",
      "supplier_reference": {
        "booking_id": "01aa00bb11cc22dd33ee44ff55667781",
        "confirmation_number": "PRV0000001",
        "provider": "provider_a",
        "booking_status": "completed",
        "booking_token": "bt1.gAAAAAB...opaque-booking-token...(about 1-2 kB; trimmed in this example)"
      },
      "total_price": 2509.96,
      "currency": "INR",
      "booking_details": {
        "details_version": "3",
        "booking": {
          "tp_booking_ref": "ORDER-10001",
          "provider": "provider_a",
          "supplier_booking_id": "01aa00bb11cc22dd33ee44ff55667781",
          "supplier_confirmation_number": "PRV0000001",
          "status": "confirmed",
          "status_source": "book_reference",
          "supplier_status": null,
          "booked_at": "2026-10-23T06:33:43+00:00"
        },
        "trip": {
          "transfer_type": "airport",
          "direction": "arrival",
          "pickup": {
            "type": "airport",
            "iata": "BOM",
            "name": "Chhatrapati Shivaji Maharaj International Airport",
            "terminal": null,
            "address": null,
            "lat": null,
            "lng": null
          },
          "dropoff": {
            "type": "address",
            "iata": null,
            "name": "The Taj Mahal Palace",
            "terminal": null,
            "address": "Apollo Bunder, Colaba, Mumbai 400001",
            "lat": 18.9217,
            "lng": 72.8332
          },
          "pickup_datetime": "2026-11-26T10:30:00+05:30",
          "timezone": "Asia/Kolkata",
          "flight": {
            "airline": "AI",
            "number": "AI101",
            "terminal": null,
            "datetime": null
          },
          "return_datetime": null,
          "hours": null,
          "locations_source": "book_snapshot",
          "route_matches_booking": null
        },
        "passengers": {
          "lead": {
            "name": "Jane Doe",
            "email": "jane.doe@example.com",
            "phone": "+442079460000"
          },
          "adults": 2,
          "children": 0,
          "infants": 0,
          "total": 2
        },
        "vehicle": {
          "category": "Sedan",
          "model": "Corolla",
          "or_similar": true,
          "max_passengers": 3,
          "max_bags": 3,
          "count": null,
          "image_url": "https://images.example.com/vehicles/sedan.png"
        },
        "service": {
          "type": null,
          "duration_minutes": 45,
          "meet_and_greet": null,
          "free_waiting_minutes": null,
          "meeting_point": "Chhatrapati Shivaji Maharaj International Airport",
          "pickup_instructions": null,
          "child_seats": null,
          "booster_seats": null,
          "pin_to_start_ride": null,
          "package": {
            "hours_included": null,
            "km_included": null,
            "days": null,
            "code": null,
            "label": null
          },
          "extra_charges": {
            "extra_km_rate": null,
            "extra_hour_rate": null,
            "night_charge": null,
            "driver_allowance": null
          },
          "driver": {
            "name": null,
            "phone": null,
            "photo_url": null,
            "vehicle_plate": null
          },
          "supplier_contact": {
            "name": null,
            "phone": null,
            "email": null,
            "support_phone": null
          }
        },
        "price": {
          "total": 2509.96,
          "currency": "INR",
          "paid": 2509.96
        },
        "cancellation": {
          "free_cancellation_until": null,
          "free_cancellation_hours": null,
          "policy_text": "100% refund if cancelled at least 24h before pickup",
          "rules": [],
          "cancelled": false,
          "cancelled_at": null,
          "refund_amount": null,
          "refund_currency": null,
          "refund_source": null,
          "cancelled_at_source": null
        },
        "supplier_voucher_url": null
      },
      "error": {
        "code": "book_outcome_unknown",
        "message": "The booking outcome could not be confirmed with the provider. Do not book again: retry the same request (same internal_reference) later, or contact support with the request_id",
        "provider": "provider_a"
      }
    }