{"openapi":"3.1.0","info":{"title":"Airport Transfer API","version":"v1","description":"Book airport and city transfers worldwide: private cars, vans and shuttles from hundreds of local providers, paid from your FlightOTA deposit and confirmed in seconds. Search, pick a quote, book."},"servers":[{"url":"https://api.flightota.com/api/v1","description":"Production"},{"url":"https://sandbox.flightota.com/api/v1","description":"Sandbox"}],"security":[{"X-Api-Key":[],"X-Api-Secret":[]}],"paths":{"/ping":{"get":{"operationId":"transfers-ping","summary":"Ping","description":"Call GET /ping first.","tags":["Getting started"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"ok":true,"partner":"PTR-000020","key_id":"ak_test_your_key_id","environment":"test","from_ip":"203.0.113.10","server_time":"2026-09-22T13:25:02+00:00"}}}},"401":{"description":"unauthenticated: Check the key and secret.\ncredential_inactive: Check the key and secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for transfers.\nproduct_not_available: Transfers are not switched on for your agency.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for transfers."}}},"product_not_available":{"value":{"error":{"code":"product_not_available","message":"Transfers are not switched on for your agency."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/transfers/search":{"post":{"operationId":"transfers-search","summary":"Search rides","description":"Quotes arrive over a few seconds: the search answers with the first ones, and more_coming: true means reading the search again brings more. Return: \"mode\": \"round_trip\", \"return_pickup_at\": \"2026-11-05 18:00\". By the hour: \"mode\": \"hourly\", \"hours\": 6 and no end.","tags":["Search rides"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"search_id":"trs_8vhdop9ilzvvjdpabo8r","expires_at":"2026-09-22T14:56:53+00:00","more_coming":false,"start":{"name":"Dubai International Airport","iata":"DXB","city":"Dubai","lat":25.2528,"lng":55.364399,"timezone":"Asia/Dubai"},"end":{"name":"Atlantis The Palm, Dubai","address":"44J8+5V - Crescent Rd - The Palm Jumeirah - Dubai - United Arab Emirates","iata":null,"city":"Dubai","lat":25.130438,"lng":55.117188,"timezone":"Asia/Dubai"},"quotes":[{"quote_id":"trq_991e55f4e7381325158b81ca","mode":"one_way","provider":{"name":"DidaGo","logo":"https://…","rating":5,"rating_count":1},"vehicle":{"type":"Sedan","class":"Standard","make":"Toyota","model":"Corolla","image":"https://…","max_passengers":3,"max_bags":3,"num_vehicles":1},"pickup_at":"2026-11-01T10:00:00+04:00","arrival_at":"2026-11-01T10:42:46+04:00","duration_minutes":45,"return":null,"cancellation":{"online":true,"policy":[{"notice_hours":24,"refund_percent":100}]},"cancellation_deadline":"2026-10-31T10:00:00+04:00","amenities":[{"key":"meet_and_greet","name":"Meet & Greet","included":false},{"key":"provider_driver_information","name":"Early driver details","included":true}],"flight_info_required":true,"extra_pax_required":false,"wait_minutes":33,"tolls_included":true,"gratuity_included":false,"notes":["You can make changes or cancel your ride at any time up to 24 hours before your scheduled pickup"],"supports":{"tracking":false,"driver_details":true},"price":{"amount":565658,"currency":"BDT"}}]}}}},"401":{"description":"unauthenticated: Check the key and secret.\ncredential_inactive: Check the key and secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for transfers.\nproduct_not_available: Transfers are not switched on for your agency.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for transfers."}}},"product_not_available":{"value":{"error":{"code":"product_not_available","message":"Transfers are not switched on for your agency."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"422":{"description":"validation_failed: See errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_failed":{"value":{"error":{"code":"validation_failed","message":"See errors."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Nothing charged; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Nothing charged; retry."}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode","start","pickup_at","passengers"],"properties":{"mode":{"type":"object","description":"The trip type."},"start":{"type":"object","description":"{ \"iata\": \"DXB\" } for an airport, { \"address\": \"…\" }, or { \"lat\": …, \"lng\": … }."},"end":{"type":"object","description":"Unless hourly. Same forms as start."},"pickup_at":{"type":"object","description":"Local time at the pickup."},"return_pickup_at":{"type":"object","description":"For round_trip. Local time of the return pickup."},"hours":{"type":"object","description":"For hourly. A car at your disposal."},"passengers":{"type":"object","description":"Passengers."},"flight_type":{"type":"object","description":"For airport pickups."}}},"example":{"mode":"one_way","start":{"iata":"DXB"},"end":{"address":"Atlantis The Palm, Dubai"},"pickup_at":"2026-11-01 10:00","passengers":2,"flight_type":"international"}}}}}},"/transfers/search/{search_id}":{"get":{"operationId":"transfers-search-get","summary":"Read all quotes so far","description":"Returns all quotes so far (call it while more_coming is true); an expired search answers 410 search_expired.","tags":["Search rides"],"parameters":[{"name":"search_id","in":"path","required":true,"description":"The search id, trs_….","schema":{"type":"string"},"example":"trs_8vhdop9ilzvvjdpabo8r"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"search_id":"trs_8vhdop9ilzvvjdpabo8r","expires_at":"2026-09-22T14:56:53+00:00","more_coming":false,"start":{"name":"Dubai International Airport","iata":"DXB","city":"Dubai","lat":25.2528,"lng":55.364399,"timezone":"Asia/Dubai"},"end":{"name":"Atlantis The Palm, Dubai","address":"44J8+5V - Crescent Rd - The Palm Jumeirah - Dubai - United Arab Emirates","iata":null,"city":"Dubai","lat":25.130438,"lng":55.117188,"timezone":"Asia/Dubai"},"quotes":[{"quote_id":"trq_991e55f4e7381325158b81ca","mode":"one_way","provider":{"name":"DidaGo","logo":"https://…","rating":5,"rating_count":1},"vehicle":{"type":"Sedan","class":"Standard","make":"Toyota","model":"Corolla","image":"https://…","max_passengers":3,"max_bags":3,"num_vehicles":1},"pickup_at":"2026-11-01T10:00:00+04:00","arrival_at":"2026-11-01T10:42:46+04:00","duration_minutes":45,"return":null,"cancellation":{"online":true,"policy":[{"notice_hours":24,"refund_percent":100}]},"cancellation_deadline":"2026-10-31T10:00:00+04:00","amenities":[{"key":"meet_and_greet","name":"Meet & Greet","included":false},{"key":"provider_driver_information","name":"Early driver details","included":true}],"flight_info_required":true,"extra_pax_required":false,"wait_minutes":33,"tolls_included":true,"gratuity_included":false,"notes":["You can make changes or cancel your ride at any time up to 24 hours before your scheduled pickup"],"supports":{"tracking":false,"driver_details":true},"price":{"amount":565658,"currency":"BDT"}}]}}}},"401":{"description":"unauthenticated: Check the key and secret.\ncredential_inactive: Check the key and secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for transfers.\nproduct_not_available: Transfers are not switched on for your agency.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for transfers."}}},"product_not_available":{"value":{"error":{"code":"product_not_available","message":"Transfers are not switched on for your agency."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"410":{"description":"search_expired: An expired search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"search_expired":{"value":{"error":{"code":"search_expired","message":"An expired search."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/transfers/search/{search_id}/quotes/{quote_id}":{"get":{"operationId":"transfers-quote-get","summary":"Read one quote","description":"Returns one quote. Quotes are valid until expires_at.","tags":["Search rides"],"parameters":[{"name":"search_id","in":"path","required":true,"description":"The search id, trs_….","schema":{"type":"string"},"example":"trs_8vhdop9ilzvvjdpabo8r"},{"name":"quote_id","in":"path","required":true,"description":"The quote id, trq_….","schema":{"type":"string"},"example":"trq_991e55f4e7381325158b81ca"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"quote_id":"trq_991e55f4e7381325158b81ca","mode":"one_way","provider":{"name":"DidaGo","logo":"https://…","rating":5,"rating_count":1},"vehicle":{"type":"Sedan","class":"Standard","make":"Toyota","model":"Corolla","image":"https://…","max_passengers":3,"max_bags":3,"num_vehicles":1},"pickup_at":"2026-11-01T10:00:00+04:00","arrival_at":"2026-11-01T10:42:46+04:00","duration_minutes":45,"return":null,"cancellation":{"online":true,"policy":[{"notice_hours":24,"refund_percent":100}]},"cancellation_deadline":"2026-10-31T10:00:00+04:00","amenities":[{"key":"meet_and_greet","name":"Meet & Greet","included":false},{"key":"provider_driver_information","name":"Early driver details","included":true}],"flight_info_required":true,"extra_pax_required":false,"wait_minutes":33,"tolls_included":true,"gratuity_included":false,"notes":["You can make changes or cancel your ride at any time up to 24 hours before your scheduled pickup"],"supports":{"tracking":false,"driver_details":true},"price":{"amount":565658,"currency":"BDT"}}}}},"401":{"description":"unauthenticated: Check the key and secret.\ncredential_inactive: Check the key and secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for transfers.\nproduct_not_available: Transfers are not switched on for your agency.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for transfers."}}},"product_not_available":{"value":{"error":{"code":"product_not_available","message":"Transfers are not switched on for your agency."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"410":{"description":"search_expired: An expired search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"search_expired":{"value":{"error":{"code":"search_expired","message":"An expired search."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/transfers/search/{search_id}/quotes/{quote_id}/book":{"post":{"operationId":"transfers-book","summary":"Book a ride","description":"Pays from your deposit and books with the provider at once. Show the traveller confirmation, pickup_instructions (may contain simple HTML) and driver_contact. A 202 (status: pending) means paid; the provider is confirming. Read the booking.","tags":["Book a ride"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"The same request with the same key returns the ride already booked.","schema":{"type":"string"},"example":"docs-ride-001"},{"name":"search_id","in":"path","required":true,"description":"The search id, trs_….","schema":{"type":"string"},"example":"trs_8vhdop9ilzvvjdpabo8r"},{"name":"quote_id","in":"path","required":true,"description":"The quote id, trq_….","schema":{"type":"string"},"example":"trq_991e55f4e7381325158b81ca"}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"example":{"status":"confirmed","booking":{"booking_ref":"TFT-Y54HH32L","state":"confirmed","created_at":"2026-09-22T14:37:23Z","client_reference":"DOCS-RIDE-001","confirmation":"MOZ6f26aec","total":{"amount":565658,"currency":"BDT"},"trip":{"mode":"one_way","start":{"name":"Dubai International Airport","iata":"DXB","…":"…"},"end":{"name":"Atlantis The Palm, Dubai","…":"…"},"pickup_at":"2026-11-01T10:00:00+04:00","return_pickup_at":null,"hours":null,"passengers":2},"ride":{"provider":{"name":"DidaGo","logo":"https://…","rating":5,"rating_count":1},"vehicle":{"type":"Sedan","make":"Toyota","model":"Corolla","max_passengers":3,"max_bags":3,"…":"…"},"pickup_at":"2026-11-01T10:00:00+04:00","arrival_at":"2026-11-01T10:42:46+04:00","duration_minutes":45,"return":null,"amenities":[{"key":"provider_driver_information","name":"Early driver details","included":true}]},"passenger":{"first_name":"Arif","last_name":"Rahman","email":"ops@agency.example","phone":"+8801711000000","country":"BD"},"extra_passengers":[],"flight":{"airline":"EK","number":"585"},"return_flight":null,"instructions":"Two bags, one child seat not needed","pickup_instructions":"If you haven't paid for the Meet&Greet service, your driver will contact you via text message to confirm the meeting point…","driver_contact":{"name":"…","phone":"…","email":"…"},"cancellation":{"online":true,"policy":[{"notice_hours":24,"refund_percent":100}],"free_until":"2026-10-31T06:00:00Z","cancelled_at":null}}}}}},"400":{"description":"idempotency_key_required: Add the header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"value":{"error":{"code":"idempotency_key_required","message":"Add the header."}}}}}}},"401":{"description":"unauthenticated: Check the key and secret.\ncredential_inactive: Check the key and secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret."}}}}}}},"402":{"description":"insufficient_funds: Deposit too low; nothing charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_funds":{"value":{"error":{"code":"insufficient_funds","message":"Deposit too low; nothing charged."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for transfers.\nproduct_not_available: Transfers are not switched on for your agency.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for transfers."}}},"product_not_available":{"value":{"error":{"code":"product_not_available","message":"Transfers are not switched on for your agency."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"409":{"description":"supplier_refused: The provider declined; nothing charged; pick another quote.\nduplicate_request: Key reused.\nrequest_in_progress: Still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_refused":{"value":{"error":{"code":"supplier_refused","message":"The provider declined; nothing charged; pick another quote."}}},"duplicate_request":{"value":{"error":{"code":"duplicate_request","message":"Key reused."}}},"request_in_progress":{"value":{"error":{"code":"request_in_progress","message":"Still running."}}}}}}},"410":{"description":"quote_expired: Search again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_expired":{"value":{"error":{"code":"quote_expired","message":"Search again."}}}}}}},"422":{"description":"validation_failed: See errors (flight number, extra passengers…).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_failed":{"value":{"error":{"code":"validation_failed","message":"See errors (flight number, extra passengers…)."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Nothing charged; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Nothing charged; retry."}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["passenger.first_name","passenger.last_name","passenger.email","passenger.phone","passenger.country"],"properties":{"passenger.first_name":{"type":"string","description":"Lead passenger."},"passenger.last_name":{"type":"string","description":"Lead passenger."},"passenger.email":{"type":"string","description":"Confirmation and driver details go here."},"passenger.phone":{"type":"string","description":"With country code, e.g. +8801711000000; the driver calls or texts it."},"passenger.country":{"type":"string","description":"ISO code."},"extra_passengers[]":{"type":"object","description":"When extra_pax_required. { \"first_name\", \"last_name\" } for each other passenger."},"flight.airline":{"type":"string","description":"When flight_info_required. e.g. EK; the driver tracks the flight."},"flight.number":{"type":"string","description":"When flight_info_required. e.g. 585; the driver tracks the flight."},"return_flight":{"type":"object","description":"Round trip with flight_info_required. Same shape."},"instructions":{"type":"string","description":"Up to 300 characters for the driver."},"client_reference":{"type":"string","description":"Your own reference."}}},"example":{"passenger":{"first_name":"Arif","last_name":"Rahman","email":"ops@agency.example","phone":"+8801711000000","country":"BD"},"flight":{"airline":"EK","number":"585"},"instructions":"Two bags, one child seat not needed","client_reference":"DOCS-RIDE-001"}}}}}},"/transfers/bookings/{booking_ref}":{"get":{"operationId":"transfers-booking-get","summary":"Read a booking","description":"Returns the booking as above. Another agency's reference answers 404 booking_not_found.","tags":["Read, list and cancel"],"parameters":[{"name":"booking_ref","in":"path","required":true,"description":"The booking reference, TFT-XXXXXXXX.","schema":{"type":"string"},"example":"TFT-Y54HH32L"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"booking":{"booking_ref":"TFT-Y54HH32L","state":"confirmed","…":"as above"}}}}},"401":{"description":"unauthenticated: Check the key and secret.\ncredential_inactive: Check the key and secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for transfers.\nproduct_not_available: Transfers are not switched on for your agency.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for transfers."}}},"product_not_available":{"value":{"error":{"code":"product_not_available","message":"Transfers are not switched on for your agency."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"404":{"description":"booking_not_found: Another agency's reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"booking_not_found":{"value":{"error":{"code":"booking_not_found","message":"Another agency's reference."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/transfers/bookings":{"get":{"operationId":"transfers-bookings-list","summary":"List bookings","description":"Newest first, 25 a page.","tags":["Read, list and cancel"],"parameters":[{"name":"state","in":"query","required":false,"description":"pending, confirmed, cancelled, rejected.","schema":{"type":"string"}},{"name":"client_reference","in":"query","required":false,"description":"Your own reference.","schema":{"type":"string"}},{"name":"created_from","in":"query","required":false,"description":"Created on or after this date.","schema":{"type":"object","description":"YYYY-MM-DD"}},{"name":"created_to","in":"query","required":false,"description":"Created on or before this date.","schema":{"type":"object","description":"YYYY-MM-DD"}},{"name":"page","in":"query","required":false,"description":"The page.","schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"Up to 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"bookings":[{"booking_ref":"TFT-Y54HH32L","state":"confirmed","…":"…"}],"page":1,"per_page":25,"total":1,"last_page":1}}}},"401":{"description":"unauthenticated: Check the key and secret.\ncredential_inactive: Check the key and secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for transfers.\nproduct_not_available: Transfers are not switched on for your agency.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for transfers."}}},"product_not_available":{"value":{"error":{"code":"product_not_available","message":"Transfers are not switched on for your agency."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/transfers/bookings/{booking_ref}/cancel":{"post":{"operationId":"transfers-cancel","summary":"Cancel","description":"No body. The provider releases the ride and the share of the charge its policy gives at that notice returns to your deposit: all of it before cancellation.free_until, the tier's refund_percent after. refund says how much came back; it is zero when the provider reports it refunded nothing, and our team then follows it up.","tags":["Read, list and cancel"],"parameters":[{"name":"booking_ref","in":"path","required":true,"description":"The booking reference, TFT-XXXXXXXX.","schema":{"type":"string"},"example":"TFT-Y54HH32L"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":"cancelled","refund":{"amount":565658,"currency":"BDT"},"booking":{"booking_ref":"TFT-Y54HH32L","state":"cancelled","cancellation":{"online":true,"policy":[{"notice_hours":24,"refund_percent":100}],"free_until":"2026-10-31T06:00:00Z","cancelled_at":"2026-09-22T14:37:40+00:00"},"…":"…"}}}}},"401":{"description":"unauthenticated: Check the key and secret.\ncredential_inactive: Check the key and secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for transfers.\nproduct_not_available: Transfers are not switched on for your agency.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for transfers."}}},"product_not_available":{"value":{"error":{"code":"product_not_available","message":"Transfers are not switched on for your agency."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"409":{"description":"too_late: No tier of the policy gives money back any more.\nnot_cancellable: This ride cannot be cancelled online (cancellation.online: false).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"too_late":{"value":{"error":{"code":"too_late","message":"No tier of the policy gives money back any more."}}},"not_cancellable":{"value":{"error":{"code":"not_cancellable","message":"This ride cannot be cancelled online (cancellation.online: false)."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: The provider did not confirm; the ride is unchanged; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"The provider did not confirm; the ride is unchanged; retry."}}}}}}}}}}},"components":{"securitySchemes":{"X-Api-Key":{"type":"apiKey","in":"header","name":"X-Api-Key"},"X-Api-Secret":{"type":"apiKey","in":"header","name":"X-Api-Secret"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}