# Generated by scripts/partner_docs/build_openapi.py from the application schema. Do not edit by hand. openapi: 3.1.0 info: title: TransferPlatform Ground Transport API version: 1.2.1 summary: Search, book and manage airport, point-to-point and hourly ground transfers from several providers. description: 'The TransferPlatform API gives you ground transfers from several providers through one contract: * **Airport transfers**: airport ↔ hotel or address, arrival and departure. * **Point-to-point transfers**: between two addresses, one way or round trip. * **Hourly hire**: a car and driver for a number of hours. **Flow:** search → recheck → book → booking details (voucher) → cancel. Each offer carries an opaque `offer_token` (send it to recheck, then the recheck''s `offer_token` to book); a booking returns a `supplier_reference` (with an opaque `booking_token`) that you send back unchanged to booking details and cancel. Tokens are encrypted, tied to your API key and cannot be edited; offer tokens expire 24 hours after the search. **Authentication:** send your API key in the `X-API-Key` header on every request except `GET /health`. Sandbox keys start with `tp_test_`, live keys with `tp_live_`. A sandbox key only ever reaches the providers'' test systems (no real bookings, nothing is charged), a live key only their production systems. A key used on the other environment answers `401 unauthorized`. **Errors:** every `4xx` / `5xx` from the API uses `{"error": {"code", "message", "provider", "request_id"}}` (`422 validation_error` adds `details[]`); provider failures arrive inside `200` responses (`errors[]` in search, `error` elsewhere). **Request ids:** every response carries `X-Request-Id` (also `error.request_id`); quote it to support. You may send your own (8–128 characters `A–Z a–z 0–9 . _ : -`). **Limits:** 600 requests per minute per API key (bursts up to 100; `429 rate_limited` with `Retry-After`); request bodies up to 256 KB (`413 payload_too_large`). **Currencies:** every price is returned in the `currency` requested in the search, for every provider and every call (recheck, book, booking details, refunds); the default is `USD` and an unsupported code answers `422 unsupported_currency`. The price is locked at search time: recheck, book and refunds use the same price basis, so a price only changes when the provider''s own price changes. **Compatibility:** within `v1`, new fields, enumeration values, error codes and providers may be added. Ignore unknown fields and handle unknown values. Examples are illustrative, based on test-environment responses with identifiers and personal data replaced; long arrays and provider-specific objects are trimmed. Guides (quickstart, booking flow, idempotency, errors, go-live checklist) are in the Guides section of the partner documentation site. ' contact: name: Pathfndr partner support email: success@pathfndr.io servers: - url: https://transfers-sandbox.pathfndr.io description: Sandbox (test keys tp_test_..., test bookings) - url: https://transfers.pathfndr.io description: Live (live keys tp_live_..., real bookings) security: - ApiKeyAuth: [] tags: - name: Search description: Find offers. - name: Booking description: Recheck, book and read bookings. - name: Cancellation description: Cancel bookings. - name: Health description: Service status. paths: /health: get: tags: - Health summary: Health check description: 'Liveness check. No API key needed. Answers `{"status": "healthy"}`.' operationId: getHealth security: [] responses: '200': description: Service is up content: application/json: schema: type: object properties: status: &id019 type: string example: healthy required: - status example: status: healthy /v1/search: post: tags: - Search summary: Search transfer offers description: 'Searches all providers enabled for your key (or the `providers` you name) in parallel and returns their offers. The body shape is chosen by `transfer_type`: omitted or `airport` → AirportSearchRequest; `point_to_point` or `intercity` → PointToPointSearchRequest; `hourly` → HourlySearchRequest. Each provider has 30 seconds to answer. Provider failures do not fail the search: they are listed in `errors[]` and the other offers are returned. Every price is in the requested `currency`; an unsupported code answers `422 unsupported_currency`. Guides: [Transfer types](/transfer-types), [Currency](/currency).' operationId: searchTransfers security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/AirportSearchRequest' - $ref: '#/components/schemas/PointToPointSearchRequest' - $ref: '#/components/schemas/HourlySearchRequest' examples: airport_arrival: summary: Airport arrival (airport → hotel) value: transfer_type: airport iata: BOM airport_name: Chhatrapati Shivaji Maharaj International Airport place: &id012 lat: 18.9217 lng: 72.8332 name: The Taj Mahal Palace address: Apollo Bunder, Colaba, Mumbai 400001 adults: 2 currency: INR source_type: air arrival_date: '2026-11-26' arrival_time: '10:30' airport_departure: summary: Airport departure (hotel → airport) value: transfer_type: airport iata: BOM airport_name: Chhatrapati Shivaji Maharaj International Airport place: lat: 18.9217 lng: 72.8332 name: The Taj Mahal Palace address: Apollo Bunder, Colaba, Mumbai 400001 adults: 2 currency: INR source_type: hotel arrival_date: '2026-11-27' arrival_time: 07:00 airport_both: summary: Airport arrival and departure in one search value: transfer_type: airport iata: BOM airport_name: Chhatrapati Shivaji Maharaj International Airport place: lat: 18.9217 lng: 72.8332 name: The Taj Mahal Palace address: Apollo Bunder, Colaba, Mumbai 400001 adults: 2 currency: INR source_type: air arrival_date: '2026-11-26' arrival_time: '10:30' departure_date: '2026-11-30' departure_time: 06:00 p2p_one_way: summary: Point-to-point, one way value: transfer_type: point_to_point pickup: &id050 lat: 18.9217 lng: 72.8332 name: The Taj Mahal Palace address: Apollo Bunder, Colaba, Mumbai 400001 city: Mumbai country_code: IN dropoff: &id051 lat: 18.5308 lng: 73.8475 name: Shivajinagar address: Shivajinagar, Pune, Maharashtra 411005 city: Pune country_code: IN pickup_date: '2026-11-27' pickup_time: 09:00 adults: 2 currency: INR p2p_round_trip: summary: Point-to-point, round trip value: transfer_type: point_to_point trip_type: round_trip pickup: lat: 18.9217 lng: 72.8332 name: The Taj Mahal Palace address: Apollo Bunder, Colaba, Mumbai 400001 city: Mumbai country_code: IN dropoff: lat: 18.5308 lng: 73.8475 name: Shivajinagar address: Shivajinagar, Pune, Maharashtra 411005 city: Pune country_code: IN pickup_date: '2026-11-27' pickup_time: 09:00 return_date: '2026-11-29' return_time: '18:00' adults: 2 currency: INR hourly: summary: Hourly hire, 4 hours value: transfer_type: hourly hours: 4 pickup: &id047 lat: 18.9217 lng: 72.8332 name: The Taj Mahal Palace address: Apollo Bunder, Colaba, Mumbai 400001 city: Mumbai country_code: IN pickup_date: '2026-11-27' pickup_time: '10:00' adults: 2 currency: INR responses: '200': description: OK headers: X-Request-Id: &id001 schema: type: string description: Id of this request (yours if you sent a valid one). Quote it to support. content: application/json: schema: $ref: '#/components/schemas/TransferSearchResponse' examples: airport_arrival: summary: Airport arrival (trimmed) value: request_id: 3e51940a-7b52-5ffe-a1c2-f7604038365d transfer_type: airport offers: &id066 - provider: provider_d transfer_type: airport direction: arrival offer_id: 1421a5071cc20000 rate_key: '7' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: &id060 total: 1317.0 currency: INR taxes_included: true vehicle: &id061 category: AC SUV Large model: Ertiga or similar image_url: https://images.example.com/vehicles/ac-suv-large.png max_passengers: 6 max_bags: 2 duration_minutes: null distance_meters: null cancellation_summary: null flight_info_required: false leg: null pickup_datetime: null pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: null included_waiting_minutes: null - provider: provider_c transfer_type: airport direction: arrival offer_id: 9f0f189773d3b1c7 rate_key: F6879023 offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 1462.33 currency: INR taxes_included: true vehicle: category: Sedan Hyundai Xcent or Similar 2018 model: Sedan Hyundai Xcent or Similar 2018 image_url: https://images.example.com/vehicles/sedan-hyundai-xcent-or-similar-2018.png max_passengers: 4 max_bags: 3 duration_minutes: 25 distance_meters: null cancellation_summary: null flight_info_required: false leg: null pickup_datetime: null pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: null included_waiting_minutes: null - provider: provider_a transfer_type: airport direction: arrival offer_id: 0f48d65d40e92602 rate_key: d320deaaed65343ed2a5b8fac337a7dd offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 2508.37 currency: INR taxes_included: true vehicle: category: Sedan model: Corolla image_url: https://images.example.com/vehicles/sedan.png max_passengers: 3 max_bags: 3 duration_minutes: 45 distance_meters: null cancellation_summary: 100% refund if cancelled at least 24h before pickup flight_info_required: true leg: null pickup_datetime: null pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: null included_waiting_minutes: null - provider: provider_b transfer_type: airport direction: arrival offer_id: 7f85ef6fe033b526 rate_key: '1902' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 16104.46 currency: INR taxes_included: true vehicle: category: economy model: Toyota Prius image_url: https://images.example.com/vehicles/economy.png max_passengers: 4 max_bags: 3 duration_minutes: null distance_meters: null cancellation_summary: null flight_info_required: false leg: null pickup_datetime: null pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: null included_waiting_minutes: null errors: [] meta: &id068 providers: &id054 - provider_a - provider_b - provider_c - provider_d directions: &id056 - arrival skipped_providers: {} offer_count: 39 sort: price_asc currencies: &id055 - INR airport_departure: summary: Airport departure (trimmed) value: request_id: 8f6e8857-b25a-5ecc-83b4-4c41115ee1aa transfer_type: airport offers: - provider: provider_d transfer_type: airport direction: departure offer_id: 1b991a806a1c4703 rate_key: '7' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 1058.0 currency: INR taxes_included: true vehicle: category: AC SUV Large model: Ertiga or similar image_url: https://images.example.com/vehicles/ac-suv-large.png max_passengers: 6 max_bags: 2 duration_minutes: null distance_meters: null cancellation_summary: null flight_info_required: false leg: null pickup_datetime: null pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: null included_waiting_minutes: null - provider: provider_c transfer_type: airport direction: departure offer_id: f63e512b6b082487 rate_key: F6879023 offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 1462.33 currency: INR taxes_included: true vehicle: category: Sedan Hyundai Xcent or Similar 2018 model: Sedan Hyundai Xcent or Similar 2018 image_url: https://images.example.com/vehicles/sedan-hyundai-xcent-or-similar-2018.png max_passengers: 4 max_bags: 3 duration_minutes: 25 distance_meters: null cancellation_summary: null flight_info_required: false leg: null pickup_datetime: null pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: null included_waiting_minutes: null - provider: provider_a transfer_type: airport direction: departure offer_id: bab783b92153cac8 rate_key: a90e73d54f9d804b2038c637ceb6f193 offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 2414.84 currency: INR taxes_included: true vehicle: category: Sedan model: Corolla image_url: https://images.example.com/vehicles/sedan.png max_passengers: 3 max_bags: 3 duration_minutes: 45 distance_meters: null cancellation_summary: 100% refund if cancelled at least 24h before pickup flight_info_required: true leg: null pickup_datetime: null pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: null included_waiting_minutes: null - provider: provider_b transfer_type: airport direction: departure offer_id: a1e1889785353ddf rate_key: '1902' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 15782.44 currency: INR taxes_included: true vehicle: category: economy model: Toyota Prius image_url: https://images.example.com/vehicles/economy.png max_passengers: 4 max_bags: 3 duration_minutes: null distance_meters: null cancellation_summary: null flight_info_required: false leg: null pickup_datetime: null pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: null included_waiting_minutes: null errors: [] meta: providers: - provider_a - provider_b - provider_c - provider_d directions: - departure skipped_providers: {} offer_count: 39 sort: price_asc currencies: - INR p2p_one_way: summary: Point-to-point, one way (trimmed) value: request_id: 3d1f5d4d-3ca1-526c-8960-cb70c96434b8 transfer_type: point_to_point offers: - provider: provider_d transfer_type: point_to_point direction: outbound offer_id: 38b24db1cfc7558b rate_key: '3' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 2266.0 currency: INR taxes_included: true vehicle: category: AC Economy model: Wagon R or Equivalent image_url: https://images.example.com/vehicles/ac-economy.png max_passengers: 4 max_bags: 1 duration_minutes: null distance_meters: null cancellation_summary: 'Free cancellation until 6h before pickup; later: INR 500 or 20% of the booking amount, whichever is less' flight_info_required: false leg: outbound pickup_datetime: 2026-11-27T09:00 pricing_model: outstation_package package: &id062 hours_included: null km_included: null days: null code: oneWay label: Outstation (150 km) extra_charges: &id063 extra_km_rate: &id046 amount: 18.0 currency: INR extra_hour_rate: null night_charge: null driver_allowance: null inclusions: &id064 tolls: true state_tax: true parking: false driver_allowance: true gratuity: false included: &id048 - Fuel Charges - Driver Allowance - Toll / State tax - GST (5%) excluded: &id049 - Pay INR 18/km after 150 km - Multiple pickups/drops - Airport Entry/Parking cancellation: &id065 free_until: null free_cancellation_hours: 6.0 rules: [] policy_text: 'Free cancellation until 6h before pickup; later: INR 500 or 20% of the booking amount, whichever is less' included_waiting_minutes: null - provider: provider_a transfer_type: point_to_point direction: outbound offer_id: 68453f24193fab43 rate_key: 3f3526b8a0171ac988390429eb820d27 offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 3962.65 currency: INR taxes_included: true vehicle: category: Bus model: null image_url: https://images.example.com/vehicles/bus.png max_passengers: 15 max_bags: 1 duration_minutes: 195 distance_meters: null cancellation_summary: 100% refund if cancelled at least 4h before pickup flight_info_required: false leg: outbound pickup_datetime: 2026-11-27T09:00 pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: free_until: null free_cancellation_hours: 4.0 rules: &id043 - hours_before_pickup: 4.0 refund_percent: 100.0 policy_text: 100% refund if cancelled at least 4h before pickup included_waiting_minutes: 30 - provider: provider_b transfer_type: point_to_point direction: outbound offer_id: 31474d69768dac75 rate_key: '1902' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 51795.83 currency: INR taxes_included: true vehicle: category: economy model: Toyota Prius image_url: https://images.example.com/vehicles/economy.png max_passengers: 4 max_bags: 3 duration_minutes: null distance_meters: null cancellation_summary: null flight_info_required: false leg: outbound pickup_datetime: 2026-11-27T09:00 pricing_model: fixed_route package: null extra_charges: null inclusions: tolls: true state_tax: null parking: null driver_allowance: null gratuity: true included: [] excluded: [] cancellation: free_until: null free_cancellation_hours: 3.0 rules: [] policy_text: null included_waiting_minutes: 15 errors: &id067 - provider: provider_c code: provider_error message: Provider search failed raw: &id052 leg: outbound meta: providers: - provider_a - provider_b - provider_c - provider_d legs: &id057 - outbound searches: &id058 - provider: provider_a leg: outbound - provider: provider_b leg: outbound - provider: provider_c leg: outbound - provider: provider_d leg: outbound skipped_providers: {} offer_count: 22 sort: price_asc currencies: - INR trip_type: one_way p2p_round_trip: summary: Point-to-point, round trip (trimmed) value: request_id: 4568dc4b-74c1-512b-aead-56df54c33088 transfer_type: point_to_point offers: - provider: provider_a transfer_type: point_to_point direction: outbound offer_id: 4cc3da7271e11591 rate_key: 3f3526b8a0171ac988390429eb820d27 offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 3962.65 currency: INR taxes_included: true vehicle: category: Bus model: null image_url: https://images.example.com/vehicles/bus.png max_passengers: 15 max_bags: 1 duration_minutes: 195 distance_meters: null cancellation_summary: 100% refund if cancelled at least 4h before pickup flight_info_required: false leg: outbound pickup_datetime: 2026-11-27T09:00 pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: free_until: null free_cancellation_hours: 4.0 rules: - hours_before_pickup: 4.0 refund_percent: 100.0 policy_text: 100% refund if cancelled at least 4h before pickup included_waiting_minutes: 30 - provider: provider_a transfer_type: point_to_point direction: return offer_id: b707526adc2287ec rate_key: e54e52fcb88703abfee20783bd03de9a offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 3962.65 currency: INR taxes_included: true vehicle: category: Bus model: null image_url: https://images.example.com/vehicles/bus.png max_passengers: 15 max_bags: 1 duration_minutes: 195 distance_meters: null cancellation_summary: 100% refund if cancelled at least 4h before pickup flight_info_required: false leg: return pickup_datetime: 2026-11-29T18:00 pricing_model: fixed_route package: null extra_charges: null inclusions: null cancellation: free_until: null free_cancellation_hours: 4.0 rules: - hours_before_pickup: 4.0 refund_percent: 100.0 policy_text: 100% refund if cancelled at least 4h before pickup included_waiting_minutes: 30 - provider: provider_d transfer_type: point_to_point direction: round_trip offer_id: 4eb6ea2ee73cd4b5 rate_key: '3' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 8181.0 currency: INR taxes_included: true vehicle: category: AC Economy model: Wagon R or Equivalent image_url: https://images.example.com/vehicles/ac-economy.png max_passengers: 4 max_bags: 1 duration_minutes: null distance_meters: null cancellation_summary: 'Free cancellation until 6h before pickup; later: INR 500 or 20% of the booking amount, whichever is less' flight_info_required: false leg: round_trip pickup_datetime: 2026-11-27T09:00 pricing_model: outstation_package package: hours_included: null km_included: null days: 3 code: roundTrip label: Outstation (600 km) extra_charges: extra_km_rate: amount: 12.0 currency: INR extra_hour_rate: null night_charge: null driver_allowance: null inclusions: tolls: false state_tax: false parking: false driver_allowance: true gratuity: null included: - Fuel Charges - Driver Allowance - GST (5%) excluded: - Pay INR 12/km after 600 km - Toll / State tax - Night Allowance - Parking cancellation: free_until: null free_cancellation_hours: 6.0 rules: [] policy_text: 'Free cancellation until 6h before pickup; later: INR 500 or 20% of the booking amount, whichever is less' included_waiting_minutes: null - provider: provider_b transfer_type: point_to_point direction: outbound offer_id: 7a3d4250bdb744f8 rate_key: '1902' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 51795.83 currency: INR taxes_included: true vehicle: category: economy model: Toyota Prius image_url: https://images.example.com/vehicles/economy.png max_passengers: 4 max_bags: 3 duration_minutes: null distance_meters: null cancellation_summary: null flight_info_required: false leg: outbound pickup_datetime: 2026-11-27T09:00 pricing_model: fixed_route package: null extra_charges: null inclusions: tolls: true state_tax: null parking: null driver_allowance: null gratuity: true included: [] excluded: [] cancellation: free_until: null free_cancellation_hours: 3.0 rules: [] policy_text: null included_waiting_minutes: 15 - provider: provider_b transfer_type: point_to_point direction: return offer_id: 55eac7f020d1b02c rate_key: '1902' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 52773.0 currency: INR taxes_included: true vehicle: category: economy model: Toyota Prius image_url: https://images.example.com/vehicles/economy.png max_passengers: 4 max_bags: 3 duration_minutes: null distance_meters: null cancellation_summary: null flight_info_required: false leg: return pickup_datetime: 2026-11-29T18:00 pricing_model: fixed_route package: null extra_charges: null inclusions: tolls: true state_tax: null parking: null driver_allowance: null gratuity: true included: [] excluded: [] cancellation: free_until: null free_cancellation_hours: 3.0 rules: [] policy_text: null included_waiting_minutes: 15 errors: - provider: provider_c code: provider_error message: Provider search failed raw: leg: outbound - provider: provider_c code: provider_error message: Provider search failed raw: leg: return meta: providers: - provider_a - provider_b - provider_c - provider_d legs: - outbound - return - round_trip searches: - provider: provider_a leg: outbound - provider: provider_a leg: return - provider: provider_b leg: outbound - provider: provider_b leg: return - provider: provider_c leg: outbound - provider: provider_c leg: return - provider: provider_d leg: round_trip skipped_providers: {} offer_count: 43 sort: price_asc currencies: - INR trip_type: round_trip hourly: summary: Hourly (trimmed) value: request_id: 19fe82d7-5cab-5759-8962-83fba57bac49 transfer_type: hourly offers: - provider: provider_d transfer_type: hourly direction: outbound offer_id: 4c294e3903461db2 rate_key: 43:440 offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 1500.0 currency: INR taxes_included: true vehicle: category: AC Mid-Size Plus model: Dzire, Etios or similar image_url: https://images.example.com/vehicles/ac-mid-size-plus.png max_passengers: 4 max_bags: 2 duration_minutes: null distance_meters: null cancellation_summary: 'Free cancellation until 2h before pickup; later: INR 500 or 20% of the booking amount, whichever is less' flight_info_required: false leg: outbound pickup_datetime: 2026-11-27T10:00 pricing_model: hourly_package package: hours_included: 4.0 km_included: 40.0 days: null code: '440' label: Local (4hr/40 km) extra_charges: extra_km_rate: amount: 12.0 currency: INR extra_hour_rate: null night_charge: null driver_allowance: null inclusions: tolls: false state_tax: false parking: false driver_allowance: true gratuity: null included: - Fuel Charges - Driver Allowance - GST (5%) excluded: - Pay INR 12/km after 40 km - Pay INR 144/hr after 4 hours - Toll / State tax - Night Allowance - Parking cancellation: free_until: null free_cancellation_hours: 2.0 rules: [] policy_text: 'Free cancellation until 2h before pickup; later: INR 500 or 20% of the booking amount, whichever is less' included_waiting_minutes: null - provider: provider_a transfer_type: hourly direction: outbound offer_id: 6f07c0af1951b62f rate_key: 6ee0dc5f7a825465f0267b13846e334f offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 3170.14 currency: INR taxes_included: true vehicle: category: Bus model: null image_url: https://images.example.com/vehicles/bus.png max_passengers: 15 max_bags: 1 duration_minutes: null distance_meters: null cancellation_summary: 100% refund if cancelled at least 4h before pickup flight_info_required: false leg: outbound pickup_datetime: 2026-11-27T10:00 pricing_model: hourly_package package: hours_included: 4.0 km_included: null days: null code: null label: null extra_charges: null inclusions: null cancellation: free_until: null free_cancellation_hours: 4.0 rules: - hours_before_pickup: 4.0 refund_percent: 100.0 policy_text: 100% refund if cancelled at least 4h before pickup included_waiting_minutes: 0 - provider: provider_b transfer_type: hourly direction: outbound offer_id: 26218a928aa973de rate_key: '1902' offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) price: total: 34166.68 currency: INR taxes_included: true vehicle: category: economy model: Toyota Prius image_url: https://images.example.com/vehicles/economy.png max_passengers: 4 max_bags: 3 duration_minutes: null distance_meters: null cancellation_summary: null flight_info_required: false leg: outbound pickup_datetime: 2026-11-27T10:00 pricing_model: hourly_package package: hours_included: 4.0 km_included: 100.0 days: null code: null label: null extra_charges: null inclusions: tolls: false state_tax: null parking: false driver_allowance: null gratuity: true included: [] excluded: [] cancellation: free_until: null free_cancellation_hours: 3.0 rules: [] policy_text: null included_waiting_minutes: 15 errors: - provider: provider_c code: mode_not_supported message: provider_c has no hourly product raw: transfer_type: hourly meta: providers: - provider_a - provider_b - provider_c - provider_d legs: - outbound searches: - provider: provider_a leg: outbound - provider: provider_b leg: outbound - provider: provider_d leg: outbound skipped_providers: &id059 provider_c: provider_c has no hourly product offer_count: 12 sort: price_asc currencies: - INR hours: 4 '401': &id002 description: 'Missing or invalid API key (`unauthorized`). Header `WWW-Authenticate: ApiKey header="X-API-Key"`.' headers: WWW-Authenticate: schema: type: string description: '`ApiKey header="X-API-Key"`' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: &id045 code: unauthorized message: Invalid API key provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '422': description: Invalid request body (`validation_error`), or an unsupported `currency` (`unsupported_currency`). headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: currency: summary: Unsupported currency value: error: code: unsupported_currency message: Currency XYZ is not supported provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 validation: summary: Validation error value: &id003 error: code: validation_error message: 'Invalid request: point_to_point.adults: Input should be greater than or equal to 1' provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 details: &id044 - loc: &id069 - point_to_point - adults msg: Input should be greater than or equal to 1 type: greater_than_equal '503': &id004 description: Authentication or booking records temporarily unavailable (`auth_unavailable`, `service_unavailable`). Nothing reached a provider. Retry with backoff. headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: auth_unavailable message: Authentication is temporarily unavailable, retry later provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '413': &id005 description: Request body larger than 256 KB (`payload_too_large`). headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: payload_too_large message: Request body larger than 262144 bytes provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '429': &id006 description: Rate limit exceeded for this API key (`rate_limited`). Wait `Retry-After` seconds. headers: X-Request-Id: *id001 Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: Rate limit exceeded for this API key; retry after the Retry-After header provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '500': &id007 description: Unexpected error (`internal_error`); no details are returned. Report it with the `request_id`. headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: internal_error message: Internal error; contact support with the request_id provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 /v1/transfer/recheck: post: tags: - Booking summary: Recheck an offer description: 'Confirms that an offer can still be booked and returns its current price and a fresh `offer_token` for book. Call it immediately before book. A provider-side failure answers `200` with `available: false` and `error`. An offer older than 24 hours answers `409 offer_expired`, an offer that can no longer be priced in the search''s currency `409 currency_unavailable` (search again); a missing, modified or foreign `offer_token` answers `422 invalid_offer_token`. Guide: [Booking flow](/booking-flow).' operationId: recheckOffer security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecheckRequest' examples: recheck: summary: Recheck an offer value: provider_context: &id053 provider: provider_a rate_key: d320deaaed65343ed2a5b8fac337a7dd offer_token: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) responses: '200': description: OK headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/RecheckResponse' examples: live_price: summary: Live price check value: available: true price_changed: false total_price: 2509.96 currency: INR cancellation_policy: null offer_token: ot1.gAAAAAB...fresh-offer-token-from-recheck...(trimmed in this example) error: null validity_check: summary: Validity check (no reprice) value: available: true price_changed: false total_price: 188.54 currency: USD cancellation_policy: null offer_token: ot1.gAAAAAB...fresh-offer-token-from-recheck...(trimmed in this example) error: null '401': *id002 '403': &id008 description: Provider not enabled for this API key (`provider_not_enabled`). headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: provider_not_enabled message: Provider 'provider_d' is not enabled for this API key provider: provider_d request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '409': description: 'The offer is older than 24 hours (`offer_expired`), or can no longer be priced in the search''s currency (`currency_unavailable`): search again.' headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: offer_expired message: 'The offer has expired: search again' provider: provider_b request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '422': description: Invalid request body (`validation_error`), or a missing / modified / foreign token (`invalid_offer_token`). headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: token: summary: Token rejected value: error: code: invalid_offer_token message: offer_token is invalid or has been modified provider: provider_a request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 validation: summary: Validation error value: *id003 '503': *id004 '413': *id005 '429': *id006 '500': *id007 /v1/transfer/book: post: tags: - Booking summary: Book an offer description: 'Books a rechecked offer. Allow up to 150 seconds. **Idempotent per `internal_reference`**: TransferPlatform records the attempt before calling the provider; re-sending the identical request returns the original booking (`Idempotent-Replayed: true`), and a different request, or one while the first is in progress or `unknown`, answers `409 duplicate_booking` without booking. A declined booking answers `200` with `status: failed`; a provider that did not answer in time `200` with `status: unknown` (re-send the identical request later). `409 offer_expired` / `409 currency_unavailable` / `422 invalid_offer_token` as for recheck. Guides: [Booking flow](/booking-flow), [Idempotency & retries](/idempotency).' operationId: createBooking security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BookRequest' examples: airport: summary: Airport arrival with flight details value: provider_context: &id013 provider: provider_a rate_key: d320deaaed65343ed2a5b8fac337a7dd offer_token: ot1.gAAAAAB...fresh-offer-token-from-recheck...(trimmed in this example) travellers: &id014 - title: Ms first_name: Jane last_name: Doe is_lead: true email: jane.doe@example.com phone: '+442079460000' phone_country_code: GB internal_reference: ORDER-10001 flight_info: &id015 airline: AI flight_number: AI101 terminal: T2 flight_datetime: 2026-11-26T09:30 p2p: summary: Point-to-point, two travellers value: provider_context: provider: provider_b rate_key: '8306' offer_token: ot1.gAAAAAB...fresh-offer-token-from-recheck...(trimmed in this example) travellers: - first_name: Jane last_name: Doe is_lead: true email: jane.doe@example.com phone: '+442079460000' phone_country_code: GB - first_name: John last_name: Doe internal_reference: ORDER-10002-OUT responses: '200': description: 'Booking outcome (`completed`, `pending`, `failed` or `unknown`). Header `Idempotent-Replayed: true` when this is the stored response of an earlier identical request.' headers: X-Request-Id: *id001 Idempotent-Replayed: &id009 schema: type: string enum: - 'true' description: Present when the response is the stored result of an earlier identical request (no new provider call). content: application/json: schema: $ref: '#/components/schemas/BookResponse' examples: airport: summary: Airport booking value: status: completed supplier_booking_id: 01aa00bb11cc22dd33ee44ff55667781 supplier_booking_ref: PRV0000001 supplier_reference: &id016 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: &id017 details_version: '3' booking: &id020 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: &id024 transfer_type: airport direction: arrival pickup: &id021 type: airport iata: BOM name: Chhatrapati Shivaji Maharaj International Airport terminal: null address: null lat: null lng: null dropoff: &id022 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: &id023 airline: AI number: AI101 terminal: null datetime: null return_datetime: null hours: null locations_source: book_snapshot route_matches_booking: null passengers: &id026 lead: &id025 name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: &id027 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: &id032 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: &id028 hours_included: null km_included: null days: null code: null label: null extra_charges: &id029 extra_km_rate: null extra_hour_rate: null night_charge: null driver_allowance: null driver: &id030 name: null phone: null photo_url: null vehicle_plate: null supplier_contact: &id031 name: null phone: null email: null support_phone: null price: &id033 total: 2509.96 currency: INR paid: 2509.96 cancellation: &id035 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: null p2p: summary: Point-to-point booking value: status: completed supplier_booking_id: INT-0000001 supplier_booking_ref: INT-0000001 supplier_reference: booking_id: INT-0000001 confirmation_number: INT-0000001 provider: provider_c booking_status: completed booking_token: bt1.gAAAAAB...opaque-booking-token...(about 1-2 kB; trimmed in this example) total_price: 70.39 currency: USD booking_details: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_c supplier_booking_id: INT-0000001 supplier_confirmation_number: INT-0000001 status: confirmed status_source: book_reference supplier_status: null booked_at: '2026-10-23T06:35:31+00:00' trip: transfer_type: point_to_point direction: outbound pickup: type: address iata: null name: Dubai Marina terminal: null address: Dubai Marina, Dubai lat: 25.0805 lng: 55.1403 dropoff: type: address iata: null name: null terminal: null address: Corniche Road, Abu Dhabi lat: 24.4539 lng: 54.3773 pickup_datetime: '2026-11-25T10:00:00+04:00' timezone: Asia/Dubai flight: airline: null number: null 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 Chevrolet Malibu 2018 model: Sedan Chevrolet Malibu 2018 or_similar: true max_passengers: 4 max_bags: 3 count: null image_url: https://images.example.com/vehicles/sedan.png service: type: null duration_minutes: 75 meet_and_greet: null free_waiting_minutes: null meeting_point: Dubai Marina 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: 70.39 currency: USD paid: null cancellation: free_cancellation_until: null free_cancellation_hours: 0.0 policy_text: null 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 error: null unknown: summary: Outcome unknown (re-send the identical request later) value: status: unknown supplier_booking_id: null supplier_booking_ref: null supplier_reference: {} total_price: null currency: null booking_details: {} error: &id018 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 '401': *id002 '403': *id008 '409': description: '`duplicate_booking`: this `internal_reference` belongs to a booking that is in progress, `unknown`, or a different request (nothing was booked by this call); or the offer expired / cannot be priced (search again).' headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: duplicate: summary: Duplicate booking value: error: code: duplicate_booking message: A booking with this internal_reference is in progress; retry this request later provider: provider_a request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 expired: summary: Offer expired value: error: code: offer_expired message: 'The offer has expired: search again' provider: provider_b request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '422': description: Invalid request body (`validation_error`), or a missing / modified / foreign token (`invalid_offer_token`). headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: token: summary: Token rejected value: error: code: invalid_offer_token message: offer_token is invalid or has been modified provider: provider_a request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 validation: summary: Validation error value: *id003 '503': *id004 '413': *id005 '429': *id006 '500': *id007 /v1/transfer/booking-details: post: tags: - Booking summary: Get booking details description: 'Returns the booking in one normalised shape for every provider: status, trip, passengers, vehicle, meeting instructions, driver, price and cancellation. Use it for vouchers and status refreshes. Only bookings made with your account can be read (`404` otherwise); a modified `supplier_reference` answers `422 invalid_booking_token`. Guide: [Booking details & vouchers](/booking-details).' operationId: getBookingDetails security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BookingDetailsRequest' examples: lookup: summary: Live lookup value: provider_context: &id036 provider: provider_a supplier_reference: &id037 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) after_cancel: summary: After a cancel, with the stored cancel response value: provider_context: provider: provider_b supplier_reference: booking_id: '58394800' confirmation_number: '58394800' provider: provider_b booking_status: completed booking_token: bt1.gAAAAAB...opaque-booking-token...(about 1-2 kB; trimmed in this example) cancel_response: &id038 '...': the cancel response you stored, unchanged responses: '200': description: OK headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/BookingDetailsResponse' examples: airport: summary: Airport, confirmed value: status: ok booking_details: &id039 details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_a supplier_booking_id: 01aa00bb11cc22dd33ee44ff55667781 supplier_confirmation_number: PRV0000001 status: confirmed status_source: supplier supplier_status: confirmed booked_at: '2026-10-23T06:33:43+00:00' trip: transfer_type: airport direction: arrival pickup: type: airport iata: BOM name: Bombay Mumbai Chhatrapati Shivaji International Airport terminal: null address: Bombay Mumbai Chhatrapati Shivaji International Airport lat: 19.088699 lng: 72.867897 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/Calcutta flight: airline: AI number: AI101 terminal: null datetime: '2026-11-26T09:30:00+05:30' return_datetime: null hours: null locations_source: supplier route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: Sedan model: Toyota Corolla or_similar: true max_passengers: 3 max_bags: 3 count: 1 image_url: https://images.example.com/vehicles/sedan.png service: type: null duration_minutes: 45 meet_and_greet: false free_waiting_minutes: 33 meeting_point: Bombay Mumbai Chhatrapati Shivaji International Airport pickup_instructions: 'For Customers Who Paid for "Meet&Greet" Service: If you have paid for the Meet&Greet service, your driver will be waiting for you at the arrival hall holding a sign with your name. For Customers Who Did Not Pay for "Meet&Greet" Service: If you havent paid for the Meet&Greet service, your driver will contact you via text message to confirm the meeting point. Please ensure your phone is switched on and accessible. In Case of Difficulty Finding Your Driver: If you cannot locate your driver, please contact the 24/7 hotline immediately: \\*Airport have the WIFI, PLEASE CONNECT IT.' 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: Example Transfers Ltd phone: '+442079460001' email: support@example.com support_phone: '+442079460002' price: total: 2509.96 currency: INR paid: 2509.96 cancellation: free_cancellation_until: '2026-11-25T10:30:00+05:30' free_cancellation_hours: 24.0 policy_text: 100% refund if cancelled at least 24h before pickup rules: &id034 - hours_before_pickup: 24.0 refund_percent: 100.0 cancelled: false cancelled_at: null refund_amount: null refund_currency: null refund_source: null cancelled_at_source: null supplier_voucher_url: null voucher_data: &id040 details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_a supplier_booking_id: 01aa00bb11cc22dd33ee44ff55667781 supplier_confirmation_number: PRV0000001 status: confirmed status_source: supplier supplier_status: confirmed booked_at: '2026-10-23T06:33:43+00:00' trip: transfer_type: airport direction: arrival pickup: type: airport iata: BOM name: Bombay Mumbai Chhatrapati Shivaji International Airport terminal: null address: Bombay Mumbai Chhatrapati Shivaji International Airport lat: 19.088699 lng: 72.867897 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/Calcutta flight: airline: AI number: AI101 terminal: null datetime: '2026-11-26T09:30:00+05:30' return_datetime: null hours: null locations_source: supplier route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: Sedan model: Toyota Corolla or_similar: true max_passengers: 3 max_bags: 3 count: 1 image_url: https://images.example.com/vehicles/sedan.png service: type: null duration_minutes: 45 meet_and_greet: false free_waiting_minutes: 33 meeting_point: Bombay Mumbai Chhatrapati Shivaji International Airport pickup_instructions: 'For Customers Who Paid for "Meet&Greet" Service: If you have paid for the Meet&Greet service, your driver will be waiting for you at the arrival hall holding a sign with your name. For Customers Who Did Not Pay for "Meet&Greet" Service: If you havent paid for the Meet&Greet service, your driver will contact you via text message to confirm the meeting point. Please ensure your phone is switched on and accessible. In Case of Difficulty Finding Your Driver: If you cannot locate your driver, please contact the 24/7 hotline immediately: \\*Airport have the WIFI, PLEASE CONNECT IT.' 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: Example Transfers Ltd phone: '+442079460001' email: support@example.com support_phone: '+442079460002' price: total: 2509.96 currency: INR paid: 2509.96 cancellation: free_cancellation_until: '2026-11-25T10:30:00+05:30' free_cancellation_hours: 24.0 policy_text: 100% refund if cancelled at least 24h before pickup rules: - hours_before_pickup: 24.0 refund_percent: 100.0 cancelled: false cancelled_at: null refund_amount: null refund_currency: null refund_source: null cancelled_at_source: null supplier_voucher_url: null error: null hourly_cancelled: summary: Hourly, cancelled value: status: ok booking_details: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_b supplier_booking_id: '60000001' supplier_confirmation_number: '60000001' status: cancelled status_source: supplier supplier_status: cancelled booked_at: '2026-10-23T06:37:19+00:00' trip: transfer_type: hourly direction: outbound pickup: type: address iata: null name: Berlin Hbf terminal: null address: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin lat: 52.5251 lng: 13.3694 dropoff: type: address iata: null name: Berlin Hbf terminal: null address: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin lat: 52.5251 lng: 13.3694 pickup_datetime: '2026-11-25T10:00:00+01:00' timezone: null flight: airline: null number: null terminal: null datetime: null return_datetime: null hours: 4 locations_source: supplier route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: economy model: Toyota Prius or_similar: true max_passengers: 3 max_bags: 3 count: null image_url: https://images.example.com/vehicles/economy.png service: type: null duration_minutes: 240 meet_and_greet: false free_waiting_minutes: 15 meeting_point: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin pickup_instructions: 'The driver will wait for you in front of the building that you have indicated as your pick-up point. In case you cannot find your driver, please contact him directly using the mobile number sent to you via SMS or use our Self Service Centre: https://provider.example.com/self-service/' child_seats: null booster_seats: null pin_to_start_ride: null package: hours_included: 4.0 km_included: 100.0 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: Example Transfers Ltd phone: '+442079460001' email: support@example.com support_phone: '+442079460002' price: total: 400.0 currency: EUR paid: null cancellation: free_cancellation_until: '2026-11-25T07:00:00+01:00' free_cancellation_hours: 3.0 policy_text: null rules: [] cancelled: true cancelled_at: '2026-10-23T06:37:22+00:00' refund_amount: 400.0 refund_currency: EUR refund_source: policy_estimate cancelled_at_source: tp_cancel supplier_voucher_url: null voucher_data: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_b supplier_booking_id: '60000001' supplier_confirmation_number: '60000001' status: cancelled status_source: supplier supplier_status: cancelled booked_at: '2026-10-23T06:37:19+00:00' trip: transfer_type: hourly direction: outbound pickup: type: address iata: null name: Berlin Hbf terminal: null address: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin lat: 52.5251 lng: 13.3694 dropoff: type: address iata: null name: Berlin Hbf terminal: null address: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin lat: 52.5251 lng: 13.3694 pickup_datetime: '2026-11-25T10:00:00+01:00' timezone: null flight: airline: null number: null terminal: null datetime: null return_datetime: null hours: 4 locations_source: supplier route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: economy model: Toyota Prius or_similar: true max_passengers: 3 max_bags: 3 count: null image_url: https://images.example.com/vehicles/economy.png service: type: null duration_minutes: 240 meet_and_greet: false free_waiting_minutes: 15 meeting_point: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin pickup_instructions: 'The driver will wait for you in front of the building that you have indicated as your pick-up point. In case you cannot find your driver, please contact him directly using the mobile number sent to you via SMS or use our Self Service Centre: https://provider.example.com/self-service/' child_seats: null booster_seats: null pin_to_start_ride: null package: hours_included: 4.0 km_included: 100.0 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: Example Transfers Ltd phone: '+442079460001' email: support@example.com support_phone: '+442079460002' price: total: 400.0 currency: EUR paid: null cancellation: free_cancellation_until: '2026-11-25T07:00:00+01:00' free_cancellation_hours: 3.0 policy_text: null rules: [] cancelled: true cancelled_at: '2026-10-23T06:37:22+00:00' refund_amount: 400.0 refund_currency: EUR refund_source: policy_estimate cancelled_at_source: tp_cancel supplier_voucher_url: null error: null airport_cancelled: summary: Airport, cancelled value: status: ok booking_details: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_c supplier_booking_id: INT-0000002 supplier_confirmation_number: INT-0000002 status: cancelled status_source: supplier supplier_status: process_canceled booked_at: '2026-10-23T06:34:03+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: '2026-11-26T09:00:00+05:30' return_datetime: null hours: null locations_source: mixed route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: private model: Sedan Hyundai Xcent or Similar 2018 or_similar: true max_passengers: 4 max_bags: 3 count: 1 image_url: https://images.example.com/vehicles/sedan.png service: type: private duration_minutes: 25 meet_and_greet: true free_waiting_minutes: 60 meeting_point: Chhatrapati Shivaji Maharaj International Airport pickup_instructions: 'How to find your driver: After collecting your luggage, proceed to the arrivals hall, where your driver will be waiting INSIDE, holding a sign with your name on it. Please show your driver a copy of your booking voucher to confirm your identity. If you have any difficulty locating your driver, please call the support hotline listed on your booking voucher. An English-speaking representative will be available to assist you. Please remember to include the international dialing code when calling from a mobile or landline phone.' child_seats: 0 booster_seats: 0 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: 17.12 currency: USD paid: null cancellation: free_cancellation_until: '2026-11-25T22:30:00+05:30' free_cancellation_hours: 12.0 policy_text: null rules: [] cancelled: true cancelled_at: '2026-10-23T06:34:07+00:00' refund_amount: 17.12 refund_currency: USD refund_source: supplier cancelled_at_source: supplier supplier_voucher_url: https://vouchers.example.com/v/0000example0000 voucher_data: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_c supplier_booking_id: INT-0000002 supplier_confirmation_number: INT-0000002 status: cancelled status_source: supplier supplier_status: process_canceled booked_at: '2026-10-23T06:34:03+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: '2026-11-26T09:00:00+05:30' return_datetime: null hours: null locations_source: mixed route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: private model: Sedan Hyundai Xcent or Similar 2018 or_similar: true max_passengers: 4 max_bags: 3 count: 1 image_url: https://images.example.com/vehicles/sedan.png service: type: private duration_minutes: 25 meet_and_greet: true free_waiting_minutes: 60 meeting_point: Chhatrapati Shivaji Maharaj International Airport pickup_instructions: 'How to find your driver: After collecting your luggage, proceed to the arrivals hall, where your driver will be waiting INSIDE, holding a sign with your name on it. Please show your driver a copy of your booking voucher to confirm your identity. If you have any difficulty locating your driver, please call the support hotline listed on your booking voucher. An English-speaking representative will be available to assist you. Please remember to include the international dialing code when calling from a mobile or landline phone.' child_seats: 0 booster_seats: 0 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: 17.12 currency: USD paid: null cancellation: free_cancellation_until: '2026-11-25T22:30:00+05:30' free_cancellation_hours: 12.0 policy_text: null rules: [] cancelled: true cancelled_at: '2026-10-23T06:34:07+00:00' refund_amount: 17.12 refund_currency: USD refund_source: supplier cancelled_at_source: supplier supplier_voucher_url: https://vouchers.example.com/v/0000example0000 error: null '401': *id002 '403': *id008 '404': &id010 description: Booking not found for your account (`booking_not_found`). headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: booking_not_found message: Booking not found provider: provider_a request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '422': description: Invalid request body (`validation_error`), or a missing / modified / foreign token (`invalid_booking_token`). headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: token: summary: Token rejected value: error: code: invalid_booking_token message: 'supplier_reference was modified: booking_id does not match booking_token' provider: provider_a request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 validation: summary: Validation error value: *id003 '503': *id004 '413': *id005 '429': *id006 '500': *id007 /v1/transfer/cancel: post: tags: - Cancellation summary: Cancel a booking description: 'Cancels a booking. Some providers answer `cancellation_pending` first; poll booking-details until `booking.status` is `cancelled`. Only bookings made with your account can be cancelled (`404` otherwise); a modified `supplier_reference` answers `422 invalid_booking_token`. A booking TransferPlatform already cancelled is answered from its records (`Idempotent-Replayed: true`) without calling the provider again; a provider that did not answer in time gives `status: unknown` (check booking-details). Guide: [Cancellations & refunds](/cancellations).' operationId: cancelBooking security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CancelRequest' examples: cancel: summary: Cancel a booking value: provider_context: &id041 provider: provider_a supplier_reference: &id042 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) reason: Customer changed travel plans responses: '200': description: OK headers: X-Request-Id: *id001 Idempotent-Replayed: *id009 content: application/json: schema: $ref: '#/components/schemas/CancelResponse' examples: refund_from_provider: summary: Cancelled, refund reported by the provider value: status: cancelled cancelled: true refund_amount: 2509.96 currency: INR refund_source: supplier refund_estimated: false cancelled_at: '2026-10-23T06:33:47+00:00' cancelled_at_source: tp_cancel error: null refund_estimated: summary: Cancelled, refund estimated from the policy value: status: cancelled cancelled: true refund_amount: 188.54 currency: USD refund_source: policy_estimate refund_estimated: true cancelled_at: '2026-10-23T06:33:56+00:00' cancelled_at_source: tp_cancel error: null pending: summary: Cancellation pending value: status: cancellation_pending cancelled: false refund_amount: 17.12 currency: USD refund_source: policy_estimate refund_estimated: true cancelled_at: null cancelled_at_source: null error: null '401': *id002 '403': *id008 '404': *id010 '422': description: Invalid request body (`validation_error`), or a missing / modified / foreign token (`invalid_booking_token`). headers: X-Request-Id: *id001 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: token: summary: Token rejected value: error: code: invalid_booking_token message: 'supplier_reference was modified: booking_id does not match booking_token' provider: provider_a request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 validation: summary: Validation error value: *id003 '503': *id004 '413': *id005 '429': *id006 '500': *id007 /v1/transfer/voucher: post: tags: - Booking summary: Get booking details (deprecated alias) description: 'Deprecated alias of `POST /v1/transfer/booking-details`: same request and response.' operationId: getVoucher deprecated: true security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BookingDetailsRequest' examples: lookup: summary: Live lookup value: provider_context: provider: provider_a 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) after_cancel: summary: After a cancel, with the stored cancel response value: provider_context: provider: provider_b supplier_reference: booking_id: '58394800' confirmation_number: '58394800' provider: provider_b booking_status: completed booking_token: bt1.gAAAAAB...opaque-booking-token...(about 1-2 kB; trimmed in this example) cancel_response: '...': the cancel response you stored, unchanged responses: '200': description: OK headers: X-Request-Id: &id011 schema: type: string description: Id of this request (yours if you sent a valid one). Quote it to support. content: application/json: schema: $ref: '#/components/schemas/BookingDetailsResponse' examples: airport: summary: Airport, confirmed value: status: ok 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: supplier supplier_status: confirmed booked_at: '2026-10-23T06:33:43+00:00' trip: transfer_type: airport direction: arrival pickup: type: airport iata: BOM name: Bombay Mumbai Chhatrapati Shivaji International Airport terminal: null address: Bombay Mumbai Chhatrapati Shivaji International Airport lat: 19.088699 lng: 72.867897 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/Calcutta flight: airline: AI number: AI101 terminal: null datetime: '2026-11-26T09:30:00+05:30' return_datetime: null hours: null locations_source: supplier route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: Sedan model: Toyota Corolla or_similar: true max_passengers: 3 max_bags: 3 count: 1 image_url: https://images.example.com/vehicles/sedan.png service: type: null duration_minutes: 45 meet_and_greet: false free_waiting_minutes: 33 meeting_point: Bombay Mumbai Chhatrapati Shivaji International Airport pickup_instructions: 'For Customers Who Paid for "Meet&Greet" Service: If you have paid for the Meet&Greet service, your driver will be waiting for you at the arrival hall holding a sign with your name. For Customers Who Did Not Pay for "Meet&Greet" Service: If you havent paid for the Meet&Greet service, your driver will contact you via text message to confirm the meeting point. Please ensure your phone is switched on and accessible. In Case of Difficulty Finding Your Driver: If you cannot locate your driver, please contact the 24/7 hotline immediately: \\*Airport have the WIFI, PLEASE CONNECT IT.' 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: Example Transfers Ltd phone: '+442079460001' email: support@example.com support_phone: '+442079460002' price: total: 2509.96 currency: INR paid: 2509.96 cancellation: free_cancellation_until: '2026-11-25T10:30:00+05:30' free_cancellation_hours: 24.0 policy_text: 100% refund if cancelled at least 24h before pickup rules: - hours_before_pickup: 24.0 refund_percent: 100.0 cancelled: false cancelled_at: null refund_amount: null refund_currency: null refund_source: null cancelled_at_source: null supplier_voucher_url: null voucher_data: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_a supplier_booking_id: 01aa00bb11cc22dd33ee44ff55667781 supplier_confirmation_number: PRV0000001 status: confirmed status_source: supplier supplier_status: confirmed booked_at: '2026-10-23T06:33:43+00:00' trip: transfer_type: airport direction: arrival pickup: type: airport iata: BOM name: Bombay Mumbai Chhatrapati Shivaji International Airport terminal: null address: Bombay Mumbai Chhatrapati Shivaji International Airport lat: 19.088699 lng: 72.867897 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/Calcutta flight: airline: AI number: AI101 terminal: null datetime: '2026-11-26T09:30:00+05:30' return_datetime: null hours: null locations_source: supplier route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: Sedan model: Toyota Corolla or_similar: true max_passengers: 3 max_bags: 3 count: 1 image_url: https://images.example.com/vehicles/sedan.png service: type: null duration_minutes: 45 meet_and_greet: false free_waiting_minutes: 33 meeting_point: Bombay Mumbai Chhatrapati Shivaji International Airport pickup_instructions: 'For Customers Who Paid for "Meet&Greet" Service: If you have paid for the Meet&Greet service, your driver will be waiting for you at the arrival hall holding a sign with your name. For Customers Who Did Not Pay for "Meet&Greet" Service: If you havent paid for the Meet&Greet service, your driver will contact you via text message to confirm the meeting point. Please ensure your phone is switched on and accessible. In Case of Difficulty Finding Your Driver: If you cannot locate your driver, please contact the 24/7 hotline immediately: \\*Airport have the WIFI, PLEASE CONNECT IT.' 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: Example Transfers Ltd phone: '+442079460001' email: support@example.com support_phone: '+442079460002' price: total: 2509.96 currency: INR paid: 2509.96 cancellation: free_cancellation_until: '2026-11-25T10:30:00+05:30' free_cancellation_hours: 24.0 policy_text: 100% refund if cancelled at least 24h before pickup rules: - hours_before_pickup: 24.0 refund_percent: 100.0 cancelled: false cancelled_at: null refund_amount: null refund_currency: null refund_source: null cancelled_at_source: null supplier_voucher_url: null error: null hourly_cancelled: summary: Hourly, cancelled value: status: ok booking_details: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_b supplier_booking_id: '60000001' supplier_confirmation_number: '60000001' status: cancelled status_source: supplier supplier_status: cancelled booked_at: '2026-10-23T06:37:19+00:00' trip: transfer_type: hourly direction: outbound pickup: type: address iata: null name: Berlin Hbf terminal: null address: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin lat: 52.5251 lng: 13.3694 dropoff: type: address iata: null name: Berlin Hbf terminal: null address: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin lat: 52.5251 lng: 13.3694 pickup_datetime: '2026-11-25T10:00:00+01:00' timezone: null flight: airline: null number: null terminal: null datetime: null return_datetime: null hours: 4 locations_source: supplier route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: economy model: Toyota Prius or_similar: true max_passengers: 3 max_bags: 3 count: null image_url: https://images.example.com/vehicles/economy.png service: type: null duration_minutes: 240 meet_and_greet: false free_waiting_minutes: 15 meeting_point: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin pickup_instructions: 'The driver will wait for you in front of the building that you have indicated as your pick-up point. In case you cannot find your driver, please contact him directly using the mobile number sent to you via SMS or use our Self Service Centre: https://provider.example.com/self-service/' child_seats: null booster_seats: null pin_to_start_ride: null package: hours_included: 4.0 km_included: 100.0 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: Example Transfers Ltd phone: '+442079460001' email: support@example.com support_phone: '+442079460002' price: total: 400.0 currency: EUR paid: null cancellation: free_cancellation_until: '2026-11-25T07:00:00+01:00' free_cancellation_hours: 3.0 policy_text: null rules: [] cancelled: true cancelled_at: '2026-10-23T06:37:22+00:00' refund_amount: 400.0 refund_currency: EUR refund_source: policy_estimate cancelled_at_source: tp_cancel supplier_voucher_url: null voucher_data: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_b supplier_booking_id: '60000001' supplier_confirmation_number: '60000001' status: cancelled status_source: supplier supplier_status: cancelled booked_at: '2026-10-23T06:37:19+00:00' trip: transfer_type: hourly direction: outbound pickup: type: address iata: null name: Berlin Hbf terminal: null address: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin lat: 52.5251 lng: 13.3694 dropoff: type: address iata: null name: Berlin Hbf terminal: null address: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin lat: 52.5251 lng: 13.3694 pickup_datetime: '2026-11-25T10:00:00+01:00' timezone: null flight: airline: null number: null terminal: null datetime: null return_datetime: null hours: 4 locations_source: supplier route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: economy model: Toyota Prius or_similar: true max_passengers: 3 max_bags: 3 count: null image_url: https://images.example.com/vehicles/economy.png service: type: null duration_minutes: 240 meet_and_greet: false free_waiting_minutes: 15 meeting_point: Berlin Hauptbahnhof, Europaplatz 1, 10557 Berlin pickup_instructions: 'The driver will wait for you in front of the building that you have indicated as your pick-up point. In case you cannot find your driver, please contact him directly using the mobile number sent to you via SMS or use our Self Service Centre: https://provider.example.com/self-service/' child_seats: null booster_seats: null pin_to_start_ride: null package: hours_included: 4.0 km_included: 100.0 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: Example Transfers Ltd phone: '+442079460001' email: support@example.com support_phone: '+442079460002' price: total: 400.0 currency: EUR paid: null cancellation: free_cancellation_until: '2026-11-25T07:00:00+01:00' free_cancellation_hours: 3.0 policy_text: null rules: [] cancelled: true cancelled_at: '2026-10-23T06:37:22+00:00' refund_amount: 400.0 refund_currency: EUR refund_source: policy_estimate cancelled_at_source: tp_cancel supplier_voucher_url: null error: null airport_cancelled: summary: Airport, cancelled value: status: ok booking_details: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_c supplier_booking_id: INT-0000002 supplier_confirmation_number: INT-0000002 status: cancelled status_source: supplier supplier_status: process_canceled booked_at: '2026-10-23T06:34:03+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: '2026-11-26T09:00:00+05:30' return_datetime: null hours: null locations_source: mixed route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: private model: Sedan Hyundai Xcent or Similar 2018 or_similar: true max_passengers: 4 max_bags: 3 count: 1 image_url: https://images.example.com/vehicles/sedan.png service: type: private duration_minutes: 25 meet_and_greet: true free_waiting_minutes: 60 meeting_point: Chhatrapati Shivaji Maharaj International Airport pickup_instructions: 'How to find your driver: After collecting your luggage, proceed to the arrivals hall, where your driver will be waiting INSIDE, holding a sign with your name on it. Please show your driver a copy of your booking voucher to confirm your identity. If you have any difficulty locating your driver, please call the support hotline listed on your booking voucher. An English-speaking representative will be available to assist you. Please remember to include the international dialing code when calling from a mobile or landline phone.' child_seats: 0 booster_seats: 0 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: 17.12 currency: USD paid: null cancellation: free_cancellation_until: '2026-11-25T22:30:00+05:30' free_cancellation_hours: 12.0 policy_text: null rules: [] cancelled: true cancelled_at: '2026-10-23T06:34:07+00:00' refund_amount: 17.12 refund_currency: USD refund_source: supplier cancelled_at_source: supplier supplier_voucher_url: https://vouchers.example.com/v/0000example0000 voucher_data: details_version: '3' booking: tp_booking_ref: ORDER-10001 provider: provider_c supplier_booking_id: INT-0000002 supplier_confirmation_number: INT-0000002 status: cancelled status_source: supplier supplier_status: process_canceled booked_at: '2026-10-23T06:34:03+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: '2026-11-26T09:00:00+05:30' return_datetime: null hours: null locations_source: mixed route_matches_booking: true passengers: lead: name: Jane Doe email: jane.doe@example.com phone: '+442079460000' adults: 2 children: 0 infants: 0 total: 2 vehicle: category: private model: Sedan Hyundai Xcent or Similar 2018 or_similar: true max_passengers: 4 max_bags: 3 count: 1 image_url: https://images.example.com/vehicles/sedan.png service: type: private duration_minutes: 25 meet_and_greet: true free_waiting_minutes: 60 meeting_point: Chhatrapati Shivaji Maharaj International Airport pickup_instructions: 'How to find your driver: After collecting your luggage, proceed to the arrivals hall, where your driver will be waiting INSIDE, holding a sign with your name on it. Please show your driver a copy of your booking voucher to confirm your identity. If you have any difficulty locating your driver, please call the support hotline listed on your booking voucher. An English-speaking representative will be available to assist you. Please remember to include the international dialing code when calling from a mobile or landline phone.' child_seats: 0 booster_seats: 0 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: 17.12 currency: USD paid: null cancellation: free_cancellation_until: '2026-11-25T22:30:00+05:30' free_cancellation_hours: 12.0 policy_text: null rules: [] cancelled: true cancelled_at: '2026-10-23T06:34:07+00:00' refund_amount: 17.12 refund_currency: USD refund_source: supplier cancelled_at_source: supplier supplier_voucher_url: https://vouchers.example.com/v/0000example0000 error: null '401': description: 'Missing or invalid API key (`unauthorized`). Header `WWW-Authenticate: ApiKey header="X-API-Key"`.' headers: WWW-Authenticate: schema: type: string description: '`ApiKey header="X-API-Key"`' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized message: Invalid API key provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '403': description: Provider not enabled for this API key (`provider_not_enabled`). headers: X-Request-Id: *id011 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: provider_not_enabled message: Provider 'provider_d' is not enabled for this API key provider: provider_d request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '404': description: Booking not found for your account (`booking_not_found`). headers: X-Request-Id: *id011 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: booking_not_found message: Booking not found provider: provider_a request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '422': description: Invalid request body (`validation_error`), or a missing / modified / foreign token (`invalid_booking_token`). headers: X-Request-Id: *id011 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: token: summary: Token rejected value: error: code: invalid_booking_token message: 'supplier_reference was modified: booking_id does not match booking_token' provider: provider_a request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 validation: summary: Validation error value: error: code: validation_error message: 'Invalid request: point_to_point.adults: Input should be greater than or equal to 1' provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 details: - loc: - point_to_point - adults msg: Input should be greater than or equal to 1 type: greater_than_equal '503': description: Authentication or booking records temporarily unavailable (`auth_unavailable`, `service_unavailable`). Nothing reached a provider. Retry with backoff. headers: X-Request-Id: *id011 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: auth_unavailable message: Authentication is temporarily unavailable, retry later provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '413': description: Request body larger than 256 KB (`payload_too_large`). headers: X-Request-Id: *id011 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: payload_too_large message: Request body larger than 262144 bytes provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '429': description: Rate limit exceeded for this API key (`rate_limited`). Wait `Retry-After` seconds. headers: X-Request-Id: *id011 Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: Rate limit exceeded for this API key; retry after the Retry-After header provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 '500': description: Unexpected error (`internal_error`); no details are returned. Report it with the `request_id`. headers: X-Request-Id: *id011 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: internal_error message: Internal error; contact support with the request_id provider: null request_id: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: 'Your API key: `tp_test_` + 43 characters (sandbox) or `tp_live_` + 43 characters (live).' schemas: AirportSearchRequest: properties: transfer_type: type: string enum: - airport default: airport description: '`airport` or omitted.' example: airport iata: type: string maxLength: 3 minLength: 3 description: Airport IATA code, upper case, for example `BOM`. example: BOM airport_name: description: Airport display name. Optional; shown in booking details when the provider does not return it. example: Chhatrapati Shivaji Maharaj International Airport type: - string - 'null' source_type: $ref: '#/components/schemas/SourceType' description: '`air`: the transfer starts at the airport (arrival leg). `hotel` or `geo`: the transfer starts at `place` (departure leg).' example: air place: $ref: '#/components/schemas/GeoPoint' description: The hotel or address end of the transfer. example: *id012 arrival_date: type: string description: 'Pickup date of the arrival leg, `YYYY-MM-DD`, local to the airport. Not format-checked by the API: send exactly this format.' example: '2026-11-26' arrival_time: type: string description: 'Pickup time of the arrival leg, `HH:MM` (24 h), local. Not format-checked by the API: send exactly this format.' example: '10:30' departure_date: description: Pickup date of the departure leg, `YYYY-MM-DD`. Send with `departure_time`. When only `arrival_*` is set and `source_type` is `hotel`/`geo`, the departure leg uses `arrival_*`. example: '2026-11-30' type: - string - 'null' departure_time: description: Pickup time of the departure leg, `HH:MM` (24 h), local. example: 06:00 type: - string - 'null' adults: type: integer minimum: 1.0 default: 1 description: Adults (and children who need a full seat). example: 2 children: type: integer minimum: 0.0 default: 0 description: Children. example: 0 infants: type: integer minimum: 0.0 default: 0 description: Infants. example: 0 currency: type: string maxLength: 3 minLength: 3 default: USD description: Requested currency, ISO 4217 (for example `INR`, `USD`, `EUR`). Every price in the response is in this currency. An unsupported code answers `422 unsupported_currency`. example: INR flight_info: anyOf: - $ref: '#/components/schemas/FlightInfo' - type: 'null' description: Not used at search; send flight details at book. example: airline: AI flight_number: AI101 flight_type: international providers: description: 'Restrict the search to these providers. Default: all providers enabled for your key.' example: - provider_a - provider_b items: $ref: '#/components/schemas/ProviderCode' type: - array - 'null' metadata: additionalProperties: true type: object description: Free-form. Not used today. example: {} type: object required: - iata - source_type - place - arrival_date - arrival_time description: 'Airport transfer search: between an airport and a hotel or address. `transfer_type` may be omitted.' BookFlightInfo: properties: airline: description: IATA airline code, for example `AI`. example: AI type: - string - 'null' flight_number: description: Flight number as printed, for example `AI101`. example: AI101 type: - string - 'null' terminal: description: Terminal. example: T2 type: - string - 'null' flight_datetime: description: 'Local airport time of landing (arrival) or take-off (departure), `YYYY-MM-DDTHH:MM[:SS]`. Default: derived from the pickup.' example: 2026-11-26T09:30 type: - string - 'null' flight_type: description: '`domestic` or `international`.' example: international type: - string - 'null' additionalProperties: true type: object description: Flight of the airport leg. Unknown fields are accepted. BookRequest: properties: provider_context: $ref: '#/components/schemas/ProviderContext' description: Provider, `rate_key` and `offer_token` (the recheck response's `offer_token`). example: *id013 travellers: items: $ref: '#/components/schemas/Traveller' type: array description: Passengers, at least one. Only the lead passenger is sent to the provider. example: *id014 internal_reference: type: string description: 'Your booking reference, unique per booking (per leg). Forwarded to the provider; returned as `booking.tp_booking_ref`. Book is idempotent on it: the identical request again returns the original booking (header `Idempotent-Replayed: true`); a different request, or one while the first is in progress or `unknown`, answers `409 duplicate_booking`.' example: ORDER-10001 flight_info: $ref: '#/components/schemas/BookFlightInfo' description: Flight details for airport transfers. example: *id015 metadata: additionalProperties: true type: object description: Free-form. Not used today. example: {} type: object required: - provider_context - travellers - internal_reference description: Book a rechecked offer. BookResponse: properties: status: type: string description: '`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_id: description: Provider booking id. example: 01aa00bb11cc22dd33ee44ff55667781 type: - string - 'null' supplier_booking_ref: description: Provider confirmation number. Show it to the customer. example: PRV0000001 type: - string - 'null' supplier_reference: $ref: '#/components/schemas/SupplierReference' description: Store it unchanged and send it to booking details and cancel. Empty (`{}`) when no booking was made (`failed`, `unknown`). example: *id016 total_price: description: Booked price, in the currency of the search. example: 2509.96 type: - number - 'null' currency: description: 'Currency of `total_price`: the search''s currency.' example: INR type: - string - 'null' booking_details: anyOf: - $ref: '#/components/schemas/BookingDetails' - type: object maxProperties: 0 description: The booking at book time, in the booking-details shape. Empty when no booking was made. example: *id017 error: anyOf: - $ref: '#/components/schemas/UnifiedError' - type: 'null' description: Set when `status` is `failed` or `unknown`. example: *id018 type: object required: - status description: Result of the booking. BookingDetails: type: object description: Normalised booking, the same shape for every provider. Every key is present; unknown values are `null`. properties: details_version: type: string description: 'Version of this structure: `"3"`.' example: '3' booking: type: object description: Booking identity and status. properties: tp_booking_ref: anyOf: - *id019 - type: 'null' description: Your `internal_reference`. example: ORDER-10001 provider: anyOf: - *id019 - type: 'null' description: Provider. example: provider_a supplier_booking_id: anyOf: - *id019 - type: 'null' description: Provider booking id. example: 01aa00bb11cc22dd33ee44ff55667781 supplier_confirmation_number: anyOf: - *id019 - type: 'null' description: Provider confirmation number. Show it on the voucher. example: PRV0000001 status: type: string enum: - confirmed - pending - cancellation_pending - cancelled - failed - unknown description: Booking status. example: confirmed status_source: description: '`supplier`: live provider lookup. `book_reference`: status recorded at book time. `null` when `status` is `unknown`.' example: book_reference enum: - supplier - book_reference type: - string - 'null' supplier_status: anyOf: - *id019 - type: 'null' description: Provider's own status word. example: confirmed booked_at: anyOf: - *id019 - type: 'null' description: Booking time, ISO 8601 UTC. example: '2026-10-23T06:33:43+00:00' required: - tp_booking_ref - provider - supplier_booking_id - supplier_confirmation_number - status - status_source - supplier_status - booked_at example: *id020 trip: type: object description: The ride. properties: transfer_type: anyOf: - *id019 - type: 'null' description: '`airport`, `point_to_point` or `hourly`.' example: airport direction: anyOf: - *id019 - type: 'null' description: '`arrival`, `departure`, `outbound`, `return` or `round_trip`.' example: arrival pickup: $ref: '#/components/schemas/BookingLocation' example: *id021 dropoff: $ref: '#/components/schemas/BookingLocation' example: *id022 pickup_datetime: anyOf: - *id019 - type: 'null' description: Pickup, ISO 8601 local time with offset when known. example: '2026-11-26T10:30:00+05:30' timezone: anyOf: - *id019 - type: 'null' description: IANA time zone of the pickup. example: Asia/Kolkata flight: type: object description: Flight. properties: airline: anyOf: - *id019 - type: 'null' description: Airline. example: AI number: anyOf: - *id019 - type: 'null' description: Flight number. example: AI101 terminal: description: Terminal. example: healthy type: - string - 'null' datetime: anyOf: - *id019 - type: 'null' description: Flight time, local. example: '2026-11-26T09:30:00+05:30' required: - airline - number - terminal - datetime example: *id023 return_datetime: description: Return pickup, for a round trip booked as one leg. example: healthy type: - string - 'null' hours: description: Booked hours (hourly hire). example: 4 type: - number - 'null' locations_source: description: Where the addresses come from. example: book_snapshot enum: - supplier - book_snapshot - mixed type: - string - 'null' route_matches_booking: description: '`false`: the provider''s route differs from what was booked. `null`: not comparable.' example: true type: - boolean - 'null' required: - transfer_type - direction - pickup - dropoff - pickup_datetime - timezone - flight - return_datetime - hours - locations_source - route_matches_booking example: *id024 passengers: type: object description: Passengers. properties: lead: type: object description: Lead passenger. properties: name: anyOf: - *id019 - type: 'null' description: Name. example: Jane Doe email: anyOf: - *id019 - type: 'null' description: Email. example: jane.doe@example.com phone: anyOf: - *id019 - type: 'null' description: Phone. example: '+442079460000' required: - name - email - phone example: *id025 adults: description: Adults. example: 2 type: - integer - 'null' children: description: Children. example: 0 type: - integer - 'null' infants: description: Infants. example: 0 type: - integer - 'null' total: description: Total passengers. example: 2 type: - integer - 'null' required: - lead - adults - children - infants - total example: *id026 vehicle: type: object description: Vehicle. properties: category: anyOf: - *id019 - type: 'null' description: Provider's category, free text. example: Sedan model: anyOf: - *id019 - type: 'null' description: Example model. example: Corolla or_similar: type: boolean description: Always `true`. example: true max_passengers: description: Seats. example: 3 type: - integer - 'null' max_bags: description: Suitcases. example: 3 type: - integer - 'null' count: description: Number of vehicles. example: 1 type: - integer - 'null' image_url: anyOf: - *id019 - type: 'null' description: Picture. example: https://images.example.com/vehicles/sedan.png required: - category - model - or_similar - max_passengers - max_bags - count - image_url example: *id027 service: type: object description: Service and meeting the driver. properties: type: anyOf: - *id019 - type: 'null' description: Provider's service type. example: private duration_minutes: description: Ride time, or booked duration (hourly). example: 45 type: - integer - 'null' meet_and_greet: description: Driver waits inside with a name sign. example: false type: - boolean - 'null' free_waiting_minutes: description: Waiting time included. example: 33 type: - integer - 'null' meeting_point: anyOf: - *id019 - type: 'null' description: Where to meet the driver. example: Chhatrapati Shivaji Maharaj International Airport pickup_instructions: anyOf: - *id019 - type: 'null' description: Provider instructions for the passenger; multi-line. example: 'For Customers Who Paid for "Meet&Greet" Service: If you have paid for the Meet&Greet service, your driver will be waiting for you at the arrival hall holding...' child_seats: description: Child seats booked. example: 0 type: - integer - 'null' booster_seats: description: Booster seats booked. example: 0 type: - integer - 'null' pin_to_start_ride: description: Code the passenger gives the driver. example: healthy type: - string - 'null' package: type: object description: Package included. properties: hours_included: description: Hours. example: 4.0 type: - number - 'null' km_included: description: Kilometres. example: 100.0 type: - number - 'null' days: description: Days. type: - integer - 'null' code: description: Package code. example: healthy type: - string - 'null' label: description: Label. example: healthy type: - string - 'null' required: - hours_included - km_included - days - code - label example: *id028 extra_charges: type: object description: Charges beyond the package. properties: extra_km_rate: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: Per extra km. extra_hour_rate: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: Per extra hour. night_charge: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: Night charge. driver_allowance: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: Driver allowance. required: - extra_km_rate - extra_hour_rate - night_charge - driver_allowance example: *id029 driver: type: object description: Driver; usually known shortly before pickup. properties: name: description: Name. example: healthy type: - string - 'null' phone: description: Phone. example: healthy type: - string - 'null' photo_url: description: Photo. example: healthy type: - string - 'null' vehicle_plate: description: Number plate. example: healthy type: - string - 'null' required: - name - phone - photo_url - vehicle_plate example: *id030 supplier_contact: type: object description: Provider customer contact. properties: name: anyOf: - *id019 - type: 'null' description: Name. example: Example Transfers Ltd phone: anyOf: - *id019 - type: 'null' description: Phone. example: '+442079460001' email: anyOf: - *id019 - type: 'null' description: Email. example: support@example.com support_phone: anyOf: - *id019 - type: 'null' description: Support phone. example: '+442079460002' required: - name - phone - email - support_phone example: *id031 required: - type - duration_minutes - meet_and_greet - free_waiting_minutes - meeting_point - pickup_instructions - child_seats - booster_seats - pin_to_start_ride - package - extra_charges - driver - supplier_contact example: *id032 price: type: object description: Price. properties: total: description: Booked price. example: 2509.96 type: - number - 'null' currency: anyOf: - *id019 - type: 'null' description: ISO 4217. example: INR paid: description: Amount in the booking currency (the search's currency), when the provider reports it. example: 2509.96 type: - number - 'null' required: - total - currency - paid example: *id033 cancellation: type: object description: Cancellation terms and outcome. properties: free_cancellation_until: anyOf: - *id019 - type: 'null' description: Last moment for free cancellation, ISO 8601 (local with offset when known). example: '2026-11-25T10:30:00+05:30' free_cancellation_hours: description: Free cancellation up to this many hours before pickup. example: 0.0 type: - number - 'null' policy_text: anyOf: - *id019 - type: 'null' description: Policy in words. example: 100% refund if cancelled at least 24h before pickup rules: type: array items: $ref: '#/components/schemas/CancellationRule' description: Refund steps. example: *id034 cancelled: type: boolean description: '`true` once cancelled.' example: false cancelled_at: anyOf: - *id019 - type: 'null' description: Cancellation time, ISO 8601 UTC. example: '2026-10-23T06:37:22+00:00' refund_amount: description: Refund. example: 400.0 type: - number - 'null' refund_currency: anyOf: - *id019 - type: 'null' description: Refund currency. example: EUR refund_source: description: Origin of the refund amount. example: policy_estimate enum: - supplier - policy_estimate type: - string - 'null' cancelled_at_source: description: Origin of `cancelled_at`. example: tp_cancel enum: - supplier - tp_cancel type: - string - 'null' required: - free_cancellation_until - free_cancellation_hours - policy_text - rules - cancelled - cancelled_at - refund_amount - refund_currency - refund_source - cancelled_at_source example: *id035 supplier_voucher_url: anyOf: - *id019 - type: 'null' description: Provider's own voucher page, when offered. example: https://vouchers.example.com/v/0000example0000 required: - details_version - booking - trip - passengers - vehicle - service - price - cancellation - supplier_voucher_url BookingDetailsRequest: properties: provider_context: $ref: '#/components/schemas/ProviderContext' description: '`{"provider": "..."}`.' example: *id036 supplier_reference: additionalProperties: true type: object description: The book response's `supplier_reference`, unchanged (with its `booking_token`). example: *id037 book_response: description: Optional stored book response. When present, details are built from it without calling the provider (book-time state). example: status: completed supplier_reference: '...': unchanged additionalProperties: true type: - object - 'null' cancel_response: description: Optional stored cancel response; fills `cancellation.cancelled_at` and the refund when the provider does not report them. Without it, our record of the cancel answer (cancelled through this API with the same key) is used. example: *id038 additionalProperties: true type: - object - 'null' type: object required: - provider_context description: Look up a booking. BookingDetailsResponse: properties: status: type: string description: 'Outcome of the lookup: `ok` or `failed`. The booking status is `booking_details.booking.status`.' example: ok booking_details: $ref: '#/components/schemas/BookingDetails' description: 'The normalised booking: the same keys for every provider.' example: *id039 voucher_data: allOf: - $ref: '#/components/schemas/BookingDetails' deprecated: true description: 'Deprecated: identical copy of `booking_details`.' example: *id040 error: anyOf: - $ref: '#/components/schemas/UnifiedError' - type: 'null' description: Set when `status` is `failed`. example: code: booking_details_failed message: 'Booking lookup failed: try again later' provider: provider_a type: object required: - status description: Normalised booking details. BookingLocation: type: object description: A pickup or drop-off location. properties: type: description: '`airport` or `address`.' example: airport enum: - airport - address type: - string - 'null' iata: anyOf: - *id019 - type: 'null' description: Airport IATA code. example: BOM name: anyOf: - *id019 - type: 'null' description: Place or airport name. example: Chhatrapati Shivaji Maharaj International Airport terminal: anyOf: - *id019 - type: 'null' description: Terminal. example: T2 address: anyOf: - *id019 - type: 'null' description: Address. example: Apollo Bunder, Colaba, Mumbai 400001 lat: description: Latitude. example: 18.9217 type: - number - 'null' lng: description: Longitude. example: 72.8332 type: - number - 'null' required: - type - iata - name - terminal - address - lat - lng CancelRequest: properties: provider_context: $ref: '#/components/schemas/ProviderContext' description: '`{"provider": "..."}`.' example: *id041 supplier_reference: additionalProperties: true type: object description: The book response's `supplier_reference`, unchanged (with its `booking_token`). example: *id042 reason: description: Free-text reason, forwarded to providers that accept one. example: Customer changed travel plans type: - string - 'null' type: object required: - provider_context - supplier_reference description: Cancel a booking. CancelResponse: properties: status: type: string description: '`cancelled` (final), `cancellation_pending` (accepted, not final yet: poll booking-details), `failed` or `unknown` (no answer in time: check booking-details).' example: cancelled cancelled: type: boolean default: false description: '`true` only when the cancellation is final.' example: true refund_amount: description: 'Refund, when known. Informational: the API does not move money.' example: 2509.96 type: - number - 'null' currency: description: 'Currency of `refund_amount`: the booking''s currency.' example: INR type: - string - 'null' refund_source: description: '`supplier` (reported by the provider) or `policy_estimate` (computed from the free-cancellation deadline).' example: supplier type: - string - 'null' refund_estimated: type: boolean default: false description: '`true` when `refund_source` is `policy_estimate`.' example: false cancelled_at: description: Cancellation time, ISO 8601 UTC. Final cancellations only. example: '2026-10-23T06:33:47+00:00' type: - string - 'null' cancelled_at_source: description: '`supplier` (provider''s time) or `tp_cancel` (when TransferPlatform received the provider''s acceptance).' example: tp_cancel type: - string - 'null' error: anyOf: - $ref: '#/components/schemas/UnifiedError' - type: 'null' description: Set when `status` is `failed` or `unknown`. example: code: cancel_failed message: 'Cancel failed: the pickup time has passed' provider: provider_a type: object required: - status description: Result of the cancellation. CancellationInfo: properties: free_until: description: Free cancellation until this pickup-local time, `YYYY-MM-DDTHH:MM:SS`, when known. example: '2026-11-26T10:30:00' type: - string - 'null' free_cancellation_hours: description: Free cancellation up to this many hours before pickup. example: 6.0 type: - number - 'null' rules: items: $ref: '#/components/schemas/CancellationRule' type: array description: Refund steps. example: *id043 policy_text: description: Policy in words. example: 'Free cancellation until 6h before pickup; later: INR 500 or 20% of the booking amount, whichever is less' type: - string - 'null' type: object description: Cancellation terms of the offer. CancellationRule: properties: hours_before_pickup: type: number description: Hours before pickup. example: 4.0 refund_percent: type: number description: Refund in percent of the price. example: 100.0 type: object required: - hours_before_pickup - refund_percent description: Refund percentage when cancelling at least `hours_before_pickup` hours before pickup. ErrorEnvelope: type: object description: Body of every HTTP 4xx / 5xx response from the API. properties: error: type: object description: The error. properties: code: type: string description: '`unauthorized`, `provider_not_enabled`, `booking_not_found`, `duplicate_booking`, `invalid_offer_token`, `invalid_booking_token`, `offer_expired`, `currency_unavailable`, `unsupported_currency`, `validation_error`, `not_found`, `method_not_allowed`, `payload_too_large`, `rate_limited`, `auth_unavailable`, `service_unavailable` or `internal_error`. New codes may be added.' example: unauthorized message: type: string description: Explanation. May change; do not parse. example: Invalid API key provider: anyOf: - *id019 - type: 'null' description: Provider concerned, when there is one. example: provider_d request_id: type: string description: Same as the `X-Request-Id` response header. Quote it to support. example: 6f1c2a9e-0d4b-4a57-9a51-3c2f8e1d7b20 details: type: array description: 'Only for `422 validation_error`: one entry per problem.' items: $ref: '#/components/schemas/ValidationIssue' example: *id044 required: - code - message - provider - request_id example: *id045 required: - error ExtraCharges: properties: extra_km_rate: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: Per extra kilometre. example: *id046 extra_hour_rate: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: Per extra hour. example: amount: 144.0 currency: INR night_charge: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: Night charge. example: amount: 250.0 currency: INR driver_allowance: anyOf: - $ref: '#/components/schemas/Money' - type: 'null' description: Driver allowance. example: amount: 300.0 currency: INR type: object description: Charges payable beyond the package. FlightInfo: properties: airline: description: IATA airline code. example: AI type: - string - 'null' flight_number: description: Flight number. example: AI101 type: - string - 'null' flight_type: description: '`domestic` or `international`.' example: international type: - string - 'null' type: object description: Flight details at search time. Accepted but not used today; send flight details at book. GeoPoint: properties: lat: type: number description: Latitude. example: 18.9217 lng: type: number description: Longitude. example: 72.8332 address: description: Address. Recommended. example: Apollo Bunder, Colaba, Mumbai 400001 type: - string - 'null' name: description: Place name, for example the hotel name. example: The Taj Mahal Palace type: - string - 'null' type: object required: - lat - lng description: Hotel or address end of an airport transfer. HourlySearchRequest: properties: pickup: $ref: '#/components/schemas/Place' description: Pickup location. example: *id047 pickup_date: type: string description: Pickup date, `YYYY-MM-DD`, local to the pickup. example: '2026-11-27' pickup_time: type: string description: Pickup time, `HH:MM` (24 h), local to the pickup. example: '10:00' adults: type: integer minimum: 1.0 default: 1 description: 'Adults. Adults + children + infants: at most 16.' example: 2 children: type: integer minimum: 0.0 default: 0 description: Children. example: 0 infants: type: integer minimum: 0.0 default: 0 description: Infants. example: 0 luggage: description: 'Number of suitcases. Used by providers that price by luggage. Default: one per adult.' example: 2 maximum: 20.0 minimum: 0.0 type: - integer - 'null' currency: type: string maxLength: 3 minLength: 3 default: USD description: Requested currency, ISO 4217 (for example `INR`, `USD`, `EUR`). Every price in the response is in this currency. An unsupported code answers `422 unsupported_currency`. example: INR providers: description: 'Restrict the search to these providers. Default: all providers enabled for your key.' example: - provider_a - provider_b items: $ref: '#/components/schemas/ProviderCode' type: - array - 'null' metadata: additionalProperties: true type: object description: Free-form. Not used today. example: {} transfer_type: type: string const: hourly default: hourly description: '`hourly`. Required.' example: hourly hours: type: integer maximum: 24.0 minimum: 1.0 description: Hours of hire, whole hours. Availability varies by location; a provider that cannot serve the requested hours or location returns no offers and is listed in `meta.skipped_providers`. example: 4 dropoff: anyOf: - $ref: '#/components/schemas/Place' - type: 'null' description: 'Where the hire ends. Default: the pickup.' example: lat: 18.9217 lng: 72.8332 name: The Taj Mahal Palace address: Apollo Bunder, Colaba, Mumbai 400001 city: Mumbai country_code: IN additionalProperties: false type: object required: - pickup - pickup_date - pickup_time - hours description: 'Hourly hire search: a car and driver at the passenger''s disposal for `hours` hours. Unknown fields are rejected.' Inclusions: properties: tolls: description: Tolls included. example: true type: - boolean - 'null' state_tax: description: State taxes included. example: true type: - boolean - 'null' parking: description: Parking included. example: false type: - boolean - 'null' driver_allowance: description: Driver allowance included. example: true type: - boolean - 'null' gratuity: description: Gratuity included. example: false type: - boolean - 'null' included: items: type: string type: array description: Included items, provider wording. example: *id048 excluded: items: type: string type: array description: Excluded items, provider wording. example: *id049 type: object description: What the price includes or excludes. Money: properties: amount: type: number description: Amount. example: 18.0 currency: type: string description: 'ISO 4217 currency: the requested currency.' example: INR type: object required: - amount - currency description: An amount in the requested currency. PackageInfo: properties: hours_included: description: Hours included. example: 4.0 type: - number - 'null' km_included: description: Kilometres included. example: 40.0 type: - number - 'null' days: description: Days included (multi-day round trips). example: 3 type: - integer - 'null' code: description: Provider package code. example: oneWay type: - string - 'null' label: description: Provider package label, for example `Local (8hr/80 km)`. example: Outstation (150 km) type: - string - 'null' type: object description: What an hourly or rental package includes. Place: properties: lat: type: number maximum: 90.0 minimum: -90.0 description: Latitude, -90 to 90. example: 18.9217 lng: type: number maximum: 180.0 minimum: -180.0 description: Longitude, -180 to 180. example: 72.8332 address: type: string minLength: 3 description: Full address, at least 3 characters. example: Apollo Bunder, Colaba, Mumbai 400001 name: description: Place name, for example a hotel or station. example: The Taj Mahal Palace type: - string - 'null' city: description: 'City. Recommended: some providers need it to find the city they serve.' example: Mumbai type: - string - 'null' country_code: description: 'ISO 3166-1 alpha-2, upper case. Recommended: providers limited to one country are skipped when the pickup is elsewhere.' example: IN maxLength: 2 minLength: 2 type: - string - 'null' tp_location_id: description: Location id agreed with Pathfndr, when you have one. example: null maxLength: 64 type: - string - 'null' additionalProperties: false type: object required: - lat - lng - address description: A pickup or drop-off location for point-to-point and hourly searches. PointToPointSearchRequest: properties: pickup: $ref: '#/components/schemas/Place' description: Pickup location. example: *id050 pickup_date: type: string description: Pickup date, `YYYY-MM-DD`, local to the pickup. example: '2026-11-27' pickup_time: type: string description: Pickup time, `HH:MM` (24 h), local to the pickup. example: 09:00 adults: type: integer minimum: 1.0 default: 1 description: 'Adults. Adults + children + infants: at most 16.' example: 2 children: type: integer minimum: 0.0 default: 0 description: Children. example: 0 infants: type: integer minimum: 0.0 default: 0 description: Infants. example: 0 luggage: description: 'Number of suitcases. Used by providers that price by luggage. Default: one per adult.' example: 2 maximum: 20.0 minimum: 0.0 type: - integer - 'null' currency: type: string maxLength: 3 minLength: 3 default: USD description: Requested currency, ISO 4217 (for example `INR`, `USD`, `EUR`). Every price in the response is in this currency. An unsupported code answers `422 unsupported_currency`. example: INR providers: description: 'Restrict the search to these providers. Default: all providers enabled for your key.' example: - provider_a - provider_b items: $ref: '#/components/schemas/ProviderCode' type: - array - 'null' metadata: additionalProperties: true type: object description: Free-form. Not used today. example: {} transfer_type: type: string default: point_to_point description: '`point_to_point` (or the alias `intercity`). Required: without it the body is read as an airport search.' enum: - point_to_point - intercity example: point_to_point trip_type: type: string enum: - one_way - round_trip default: one_way description: '`one_way`, or `round_trip` (requires `return_date` and `return_time`).' example: round_trip dropoff: $ref: '#/components/schemas/Place' description: Drop-off location, at least 1 km from the pickup. example: *id051 return_date: description: 'Round trip only: return pickup date, `YYYY-MM-DD`, local to the drop-off.' example: '2026-11-29' type: - string - 'null' return_time: description: 'Round trip only: return pickup time, `HH:MM`. At least 1 hour after the pickup.' example: '18:00' type: - string - 'null' additionalProperties: false type: object required: - pickup - pickup_date - pickup_time - dropoff description: Point-to-point transfer search between two addresses (one way or round trip). Unknown fields are rejected. `intercity` is accepted as an alias of `point_to_point`. Price: properties: total: type: number description: Total price for the vehicle. example: 1317.0 currency: type: string description: 'ISO 4217 currency: the requested currency.' example: INR taxes_included: type: boolean default: true description: 'Always `true`: prices include taxes.' example: true type: object required: - total - currency description: Price of the offer for the whole vehicle (not per passenger), in the requested currency. ProviderCode: type: string pattern: ^[a-z0-9_]+$ example: provider_a description: Provider id, as returned in each offer's `provider`. Only the providers enabled for your API key are accepted; an unknown id answers `422`. The ids enabled for your account are listed on your onboarding sheet. Examples in this documentation use neutral ids (`provider_a`, `provider_b`, ...). ProviderContext: properties: provider: type: string description: 'Provider id: the offer''s `provider`, unchanged (case-insensitive).' example: provider_a rate_key: description: The offer's `rate_key`. Recommended for recheck and book. example: d320deaaed65343ed2a5b8fac337a7dd type: - string - 'null' search_id: description: Not needed. example: null type: - string - 'null' offer_token: description: 'Recheck: the offer''s `offer_token`. Book: the recheck response''s `offer_token`. Required for recheck and book; not used by booking-details and cancel.' example: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) type: - string - 'null' type: object required: - provider description: Identifies the provider and the offer or booking. ProviderSearchError: properties: provider: type: string description: Provider. example: provider_c code: type: string description: '`provider_not_enabled`, `mode_not_supported`, `city_not_mapped`, `lead_time_too_short`, `timeout`, `provider_rejected`, `provider_error` or `search_error`. New codes may be added.' example: provider_error message: type: string description: Explanation. Do not parse. example: Provider search failed raw: description: 'Detail: only `leg`, `direction`, `transfer_type`, `timeout_seconds` or `min_lead_hours`, when relevant.' example: *id052 additionalProperties: true type: - object - 'null' type: object required: - provider - code - message description: A provider that failed, was skipped or has no product for this search. The other providers' offers are still returned. RecheckRequest: properties: provider_context: $ref: '#/components/schemas/ProviderContext' description: Provider, `rate_key` and the offer's `offer_token`. example: *id053 type: object required: - provider_context description: Recheck an offer before booking. RecheckResponse: properties: available: type: boolean description: '`true`: the offer can be booked.' example: true price_changed: type: boolean default: false description: '`true` when the provider''s price differs from the search price by more than 0.01.' example: false total_price: description: Current price, in the currency of the search. example: 2509.96 type: - number - 'null' currency: description: 'Currency of `total_price`: the search''s currency.' example: INR type: - string - 'null' cancellation_policy: description: Reserved; `null` today. example: null additionalProperties: true type: - object - 'null' offer_token: description: Opaque, encrypted string. Store it and send it back unchanged; it cannot be read or edited (a modified token is rejected with `422`). Send it as `provider_context.offer_token` to book. Same validity as the search's token (a recheck does not extend it). `null` when the recheck failed. example: ot1.gAAAAAB...fresh-offer-token-from-recheck...(trimmed in this example) type: - string - 'null' error: anyOf: - $ref: '#/components/schemas/UnifiedError' - type: 'null' description: Why `available` is `false`. example: code: recheck_failed message: The offer can no longer be booked provider: provider_a type: object required: - available description: Current availability and price of the offer. SearchMeta: type: object additionalProperties: true description: Search summary. New keys may be added. properties: providers: type: array items: *id019 description: Providers considered. example: *id054 offer_count: type: integer description: Number of offers. example: 39 sort: type: string description: 'Sort order applied: `price_asc`.' example: price_asc currencies: type: array items: *id019 description: The requested currency (empty when there are no offers). example: *id055 directions: type: array items: *id019 description: 'Airport: legs searched (`arrival`, `departure`).' example: *id056 legs: type: array items: *id019 description: 'Point-to-point and hourly: legs searched.' example: *id057 searches: type: array items: type: object properties: provider: *id019 leg: *id019 description: 'Point-to-point and hourly: provider and leg pairs actually searched.' example: *id058 skipped_providers: type: object additionalProperties: *id019 description: 'Always present (`{}` when empty). Providers that returned no offers for a non-error reason: `provider_not_enabled`, `no_availability` (searched, no product for this route and date), or a short text when the provider cannot serve the request.' example: *id059 trip_type: type: string description: 'Point-to-point: `one_way` or `round_trip`.' example: one_way hours: type: integer description: 'Hourly: requested hours.' example: 4 required: - providers - offer_count - sort - currencies SourceType: type: string enum: - air - hotel - geo description: '`air`: pickup at the airport (arrival); `hotel` / `geo`: pickup at `place` (departure).' SupplierReference: type: object additionalProperties: true description: Reference of a booking. Store the whole object and send it back unchanged; new keys may be added. properties: booking_id: anyOf: - *id019 - type: 'null' description: Provider booking id. example: 01aa00bb11cc22dd33ee44ff55667781 confirmation_number: anyOf: - *id019 - type: 'null' description: Provider confirmation number. example: PRV0000001 provider: anyOf: - *id019 - type: 'null' description: Provider. example: provider_a booking_status: anyOf: - *id019 - type: 'null' description: Book status at book time (`completed`, `pending`). example: completed booking_token: type: string description: 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) required: - booking_token TransferOffer: properties: provider: type: string description: Provider of the offer. Send it as `provider_context.provider`. example: provider_d transfer_type: type: string default: airport description: '`airport`, `point_to_point` or `hourly`.' example: airport direction: type: string description: 'Airport: `arrival` or `departure`. Point-to-point and hourly: the leg (`outbound`, `return`, `round_trip`).' example: arrival offer_id: type: string description: 'Id of the offer within this search response. A new id is generated on every search: do not store it across searches.' example: 1421a5071cc20000 rate_key: type: string description: Send it as `provider_context.rate_key` to recheck and book. example: '7' offer_token: description: Opaque, encrypted string. Store it and send it back unchanged; it cannot be read or edited (a modified token is rejected with `422`). Send it as `provider_context.offer_token` to recheck. Valid for 24 hours from the search (`409 offer_expired` afterwards); only for your API key. example: ot1.gAAAAAB...opaque-offer-token...(about 1 kB; trimmed in this example) type: - string - 'null' price: $ref: '#/components/schemas/Price' description: Price for the vehicle. example: *id060 vehicle: anyOf: - $ref: '#/components/schemas/VehicleInfo' - type: 'null' description: Vehicle category. example: *id061 duration_minutes: description: Estimated ride time, when known. example: 25 type: - integer - 'null' distance_meters: description: Route distance, when known. example: 148000 type: - integer - 'null' cancellation_summary: description: Cancellation terms in words, when known. example: 100% refund if cancelled at least 24h before pickup type: - string - 'null' flight_info_required: type: boolean default: false description: '`true`: flight details are required at book.' example: false leg: description: 'Point-to-point and hourly: `outbound`, `return` (of a round trip searched as two legs) or `round_trip` (a round trip sold as one leg). `null` for airport offers.' example: outbound enum: - outbound - return - round_trip type: - string - 'null' pickup_datetime: description: Pickup of this leg, local, `YYYY-MM-DDTHH:MM`. `null` for airport offers. example: 2026-11-27T09:00 type: - string - 'null' pricing_model: type: string enum: - fixed_route - hourly_package - outstation_package default: fixed_route description: '`fixed_route`: price for the route. `hourly_package`: hours (and km) included. `outstation_package`: multi-day or long-distance package with a kilometre allowance, extra km charged.' example: fixed_route package: anyOf: - $ref: '#/components/schemas/PackageInfo' - type: 'null' description: What the package includes (hourly and package offers). example: *id062 extra_charges: anyOf: - $ref: '#/components/schemas/ExtraCharges' - type: 'null' description: Charges payable beyond the package. example: *id063 inclusions: anyOf: - $ref: '#/components/schemas/Inclusions' - type: 'null' description: What the price includes or excludes. example: *id064 cancellation: anyOf: - $ref: '#/components/schemas/CancellationInfo' - type: 'null' description: 'Cancellation terms. `null` for airport offers today: use `cancellation_summary`.' example: *id065 included_waiting_minutes: description: Waiting time included at pickup, when known. example: 30 type: - integer - 'null' type: object required: - provider - direction - offer_id - rate_key - price description: One bookable vehicle option for one leg, from one provider. TransferSearchResponse: properties: request_id: type: string description: Id of this search. Quote it to support. example: 3e51940a-7b52-5ffe-a1c2-f7604038365d transfer_type: type: string default: airport description: '`airport`, `point_to_point` or `hourly`.' example: airport offers: items: $ref: '#/components/schemas/TransferOffer' type: array description: Offers, all in the requested currency, sorted by price ascending. example: *id066 errors: items: $ref: '#/components/schemas/ProviderSearchError' type: array description: Providers that failed or were skipped. May be non-empty even when offers are returned. example: *id067 meta: $ref: '#/components/schemas/SearchMeta' description: 'Search summary: providers considered, legs or directions, offer count, sort order, currency and `skipped_providers` (always an object).' example: *id068 type: object required: - request_id description: Offers from all providers queried, plus per-provider errors. Traveller: properties: title: description: '`Mr`, `Ms`, `Mrs`, ...' example: Ms type: - string - 'null' first_name: type: string description: Given name. example: Jane last_name: type: string description: Family name. example: Doe is_lead: type: boolean default: false description: 'Lead passenger. Default: the first traveller.' example: true email: description: Lead passenger email. Strongly recommended; some providers require it. example: jane.doe@example.com type: - string - 'null' phone: description: Lead passenger mobile, E.164 with `+`. Strongly recommended; some providers require it. example: '+442079460000' type: - string - 'null' phone_country_code: description: ISO 3166-1 alpha-2 country of the phone number (for example `GB`), not the dial code. example: GB type: - string - 'null' nationality: description: ISO 3166-1 alpha-2. example: GB type: - string - 'null' extra: additionalProperties: true type: object description: Free-form. Not forwarded to providers. example: {} additionalProperties: true type: object required: - first_name - last_name description: A passenger. Only the lead passenger's details are sent to the provider. UnifiedError: properties: code: type: string description: '`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 message: type: string description: 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...' provider: description: Provider. example: provider_a type: - string - 'null' type: object required: - code - message description: Why a recheck, book, booking-details or cancel did not succeed. ValidationIssue: type: object description: One validation problem. properties: loc: type: array items: anyOf: - *id019 - type: integer description: Path of the offending field inside the body, for example `["point_to_point", "adults"]`; empty for a body that is not valid JSON. example: *id069 msg: type: string description: Explanation. example: Input should be greater than or equal to 1 type: type: string description: Kind of problem, for example `missing`, `greater_than_equal`, `value_error`, `extra_forbidden`, `json_invalid`. example: greater_than_equal required: - loc - msg - type VehicleInfo: properties: category: description: Provider's vehicle category, free text, not normalised. example: AC SUV Large type: - string - 'null' model: description: Example model, "or similar". example: Ertiga or similar type: - string - 'null' image_url: description: Picture of the category. example: https://images.example.com/vehicles/ac-suv-large.png type: - string - 'null' max_passengers: description: Seats. example: 6 type: - integer - 'null' max_bags: description: Suitcases. example: 2 type: - integer - 'null' type: object description: Vehicle category of the offer. `category` is the provider's own wording.