Skip to main content

BookingDetails

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
    BookingDetails
    {
      "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": "[email protected]",
          "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": "https://vouchers.example.com/v/0000example0000"
    }