{"openapi":"3.1.0","info":{"title":"Paxvel Hub API","version":"1.0.0","description":"Quote and book airport transfers, hourly chauffeur services and airport services (fast track, lounge, meet & assist).\n\nAuthentication: `Authorization: Bearer <key>`. Test keys (`pxt_test_…`) use real prices but create sandbox bookings (reference `TEST-…`) that never reach operations. Live keys (`pxt_live_…`) are enabled after go-live approval.\n\nPrices are final, in your account currency, VAT included. An `offer_id` is valid for 30 minutes. Send an `Idempotency-Key` header with POST requests to make retries safe.\n\nErrors: `{\"error\": {\"code\", \"message\", \"details\"}, \"request_id\"}`. Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` on 429.\n\nWebhooks: POST JSON to your URL with header `Paxvel-Signature: t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(secret, t + \".\" + raw body). Events: booking.created, booking.updated, booking.cancelled, ping. Respond 2xx within 8 seconds; failed deliveries are retried 6 times (after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h, about 33 hours in total), then marked failed."},"servers":[{"url":"https:\/\/paxvelhub.com\/api\/v1"}],"security":[{"bearer":[]}],"paths":{"\/ping":{"get":{"summary":"Check your key","tags":["General"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"request_id":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/vehicle-types":{"get":{"summary":"Vehicle types","tags":["General"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/VehicleType"}},"request_id":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/locations":{"get":{"summary":"Search airports, hotels and other locations","tags":["General"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"type","in":"query","schema":{"type":"string","enum":["airport","hotel","port","station","other"]}},{"name":"country","in":"query","schema":{"type":"string","example":"TR"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":50}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Location"}},"request_id":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/quotes":{"post":{"summary":"Get prices (transfer or hourly)","tags":["Booking"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["from","date","time"],"properties":{"service":{"type":"string","enum":["transfer","hourly"],"default":"transfer"},"from":{"type":"object","description":"One of: location_id, iata, or lat + lng + address.","properties":{"location_id":{"type":"integer","example":12},"iata":{"type":"string","example":"AYT"},"lat":{"type":"number","example":36.862},"lng":{"type":"number","example":31.056},"address":{"type":"string","maxLength":300,"example":"Regnum Carya, Belek"},"country":{"type":"string","example":"TR"}}},"to":{"type":"object","description":"One of: location_id, iata, or lat + lng + address.","properties":{"location_id":{"type":"integer","example":12},"iata":{"type":"string","example":"AYT"},"lat":{"type":"number","example":36.862},"lng":{"type":"number","example":31.056},"address":{"type":"string","maxLength":300,"example":"Regnum Carya, Belek"},"country":{"type":"string","example":"TR"}}},"date":{"type":"string","format":"date","example":"2026-11-20"},"time":{"type":"string","example":"14:30","description":"Local time at pick-up"},"hours":{"type":"number","description":"Hourly service only (1–48)"},"passengers":{"type":"object","properties":{"adults":{"type":"integer","default":1},"children":{"type":"integer"},"infants":{"type":"integer"}}},"luggage":{"type":"integer"},"instant_only":{"type":"boolean","default":false,"description":"Return only offers that can be confirmed instantly (confirmation = instant). Always on when your account is set to instant confirmation only."}}}}}},"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Quote"},"request_id":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/flights\/pickup-time":{"post":{"summary":"Suggested pick-up time from a flight number","tags":["Booking"],"description":"Looks up the flight and suggests the pick-up time: for trips to the airport the latest pick-up so the passenger is at the airport in time (international 3 h, domestic 1.5 h before departure by default) including driving time and a rush-hour margin; for trips from the airport the landing time. Use it as a helper before requesting quotes.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["flight_number","date","from","to"],"properties":{"flight_number":{"type":"string","example":"TK1937"},"date":{"type":"string","format":"date","example":"2026-11-20","description":"Local date of the transfer"},"from":{"type":"object","description":"One of: location_id, iata, or lat + lng + address.","properties":{"location_id":{"type":"integer","example":12},"iata":{"type":"string","example":"AYT"},"lat":{"type":"number","example":36.862},"lng":{"type":"number","example":31.056},"address":{"type":"string","maxLength":300,"example":"Regnum Carya, Belek"},"country":{"type":"string","example":"TR"}}},"to":{"type":"object","description":"One of: location_id, iata, or lat + lng + address.","properties":{"location_id":{"type":"integer","example":12},"iata":{"type":"string","example":"AYT"},"lat":{"type":"number","example":36.862},"lng":{"type":"number","example":31.056},"address":{"type":"string","maxLength":300,"example":"Regnum Carya, Belek"},"country":{"type":"string","example":"TR"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/PickupTime"},"request_id":{"type":"string"}}}}}},"404":{"description":"Flight not found (flight_not_found)"},"503":{"description":"Flight data not available (flight_data_unavailable)"},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/airport-services":{"get":{"summary":"Airport services with prices","tags":["Booking"],"parameters":[{"name":"airport","in":"query","required":true,"schema":{"type":"string","example":"IST"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"time","in":"query","schema":{"type":"string","example":"09:30"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["arrival","departure"]}},{"name":"adults","in":"query","schema":{"type":"integer"}},{"name":"children","in":"query","schema":{"type":"integer"}},{"name":"infants","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/AirportService"}},"request_id":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/bookings":{"post":{"summary":"Create a booking from offers","tags":["Booking"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":80}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["lead_passenger"],"properties":{"items":{"type":"array","maxItems":10,"items":{"type":"object","required":["offer_id"],"properties":{"offer_id":{"type":"string"},"flight_number":{"type":"string","example":"TK2412"},"note":{"type":"string"}}}},"services":{"type":"array","maxItems":10,"items":{"type":"object","required":["offer_id"],"properties":{"offer_id":{"type":"string"},"flight_number":{"type":"string"},"at":{"type":"string","example":"2026-11-20 09:30"},"for_item":{"type":"integer","minimum":0,"description":"Index (0-based) in `items` of the transfer this service belongs to. Optional."}}}},"lead_passenger":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}}},"passengers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["adult","child","infant"]}}}},"reference":{"type":"string","maxLength":80,"description":"Your own booking reference"},"note":{"type":"string","maxLength":2000},"instant_only":{"type":"boolean","default":false,"description":"Create the booking only if it can be confirmed instantly; otherwise nothing is created and you get 409 not_instant with details.reason (no_price, short_notice, credit_limit). Always on when your account is set to instant confirmation only."}}}}}},"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Booking"},"request_id":{"type":"string"}}}}}},"409":{"$ref":"#\/components\/responses\/Error"},"410":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"get":{"summary":"List bookings","tags":["Booking"],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"reference","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Booking"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}}},"request_id":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/bookings\/{reference}":{"get":{"summary":"Get a booking","tags":["Booking"],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","example":"PXT-01234"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Booking"},"request_id":{"type":"string"}}}}}},"404":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/bookings\/{reference}\/cancel":{"post":{"summary":"Cancel a booking (fee per cancellation policy)","tags":["Booking"],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application\/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Booking"},"request_id":{"type":"string"}}}}}},"404":{"$ref":"#\/components\/responses\/Error"},"409":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/bookings\/{reference}\/offer\/accept":{"post":{"summary":"Accept the offer on an on-request booking (status offered → confirmed; card accounts get a payment_url and are confirmed after payment)","tags":["Booking"],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Booking"},"request_id":{"type":"string"}}}}}},"404":{"$ref":"#\/components\/responses\/Error"},"409":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/bookings\/{reference}\/offer\/decline":{"post":{"summary":"Decline the offer on an on-request booking (booking is cancelled free of charge)","tags":["Booking"],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application\/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Booking"},"request_id":{"type":"string"}}}}}},"404":{"$ref":"#\/components\/responses\/Error"},"409":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/test\/bookings\/{reference}\/simulate":{"post":{"summary":"Test only: simulate a status change","tags":["Testing"],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","example":"TEST-1A2B3C4"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["payment_completed","confirmed","driver_assigned","on_route","completed","no_show","on_request","offered"]}}}}}},"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Booking"},"request_id":{"type":"string"}}}}}},"404":{"$ref":"#\/components\/responses\/Error"},"409":{"$ref":"#\/components\/responses\/Error"},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}},"\/test\/webhook":{"post":{"summary":"Send a ping webhook to your URL now","tags":["Testing"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"request_id":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"responses":{"Error":{"description":"Error","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}},"request_id":{"type":"string"}}}}}}},"schemas":{"VehicleType":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"},"max_passengers":{"type":"integer"},"max_luggage":{"type":"integer"},"image_url":{"type":"string"},"models":{"type":["string","null"],"description":"Example models, e.g. \"Mercedes Vito or similar\""},"free_waiting_minutes":{"type":["integer","null"],"description":"Free waiting time included in the price"}}},"AirportService":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","example":"fast_track"},"name":{"type":"string"},"airport":{"type":"string","example":"IST"},"terminal":{"type":["string","null"]},"meeting_point":{"type":["string","null"]},"description":{"type":["string","null"]},"location":{"type":["string","null"],"description":"Directions inside the airport"},"zone":{"type":["string","null"],"enum":["airside","landside",null]},"opening_hours":{"type":["string","null"]},"max_stay_hours":{"type":["number","null"]},"conditions":{"type":"array","items":{"type":"string"}},"features":{"type":"array","items":{"type":"string"},"description":"Keys such as wifi, shower, alcohol, aircon, accessible"},"children_allowed":{"type":"boolean"},"infants_allowed":{"type":"boolean"},"photos":{"type":"array","items":{"type":"string","format":"uri"}},"options":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"name":{"type":"string"},"duration_hours":{"type":["number","null"]},"direction":{"type":["string","null"],"enum":["any","arrival","departure","transit",null],"description":"any = valid for both directions"},"price":{"type":["number","null"]},"currency":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}},"Location":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"iata":{"type":"string"},"name":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"}}},"Offer":{"type":"object","properties":{"offer_id":{"type":"string"},"vehicle_type":{"$ref":"#\/components\/schemas\/VehicleType","description":"Offers carry id, code, name, max_passengers and max_luggage; see \/vehicle-types for the full card"},"price":{"type":["number","null"],"description":"null = price on request"},"currency":{"type":"string"},"confirmation":{"type":"string","enum":["instant","on_request"]},"free_cancellation_hours":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"}}},"Quote":{"type":"object","properties":{"service":{"type":"string"},"currency":{"type":"string"},"distance_km":{"type":["number","null"]},"timezone":{"type":"string"},"out_of_service_area":{"type":"boolean"},"instant_only":{"type":"boolean","description":"True when only instantly confirmable offers are returned."},"offers":{"type":"array","items":{"$ref":"#\/components\/schemas\/Offer"}},"airport_services":{"type":"array","description":"Airport services (fast track, lounge, meet & greet) available at the airport ends of this transfer. Empty for hourly quotes.","items":{"$ref":"#\/components\/schemas\/ServiceHint"}}}},"ServiceHint":{"type":"object","properties":{"airport":{"type":"string","example":"AYT"},"direction":{"type":"string","enum":["arrival","departure"]},"count":{"type":"integer"},"types":{"type":"array","items":{"type":"string"}},"from":{"type":["object","null"],"properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"suggested_at":{"type":["string","null"],"description":"Suggested service time (airport local), departure: estimated arrival at the airport"},"search":{"type":"string","description":"GET path that lists these services with offer_id values"}}},"PickupTime":{"type":"object","properties":{"flight_number":{"type":"string","example":"TK1937"},"airline":{"type":["string","null"]},"departure":{"type":"object","properties":{"airport":{"type":["string","null"],"example":"IST"},"scheduled_at":{"type":["string","null"],"example":"2026-11-20T07:40","description":"Local time"},"terminal":{"type":["string","null"]}}},"arrival":{"type":"object","properties":{"airport":{"type":["string","null"]},"scheduled_at":{"type":["string","null"]},"terminal":{"type":["string","null"]}}},"domestic":{"type":["boolean","null"]},"trip":{"type":["string","null"],"enum":["to_airport","from_airport",null]},"airport_match":{"type":"boolean","description":"false when the flight does not use the airport of this trip"},"airport_before_minutes":{"type":["integer","null"]},"drive_minutes":{"type":["integer","null"]},"rush_minutes":{"type":["integer","null"]},"suggested_pickup_at":{"type":["string","null"],"example":"2026-11-20T03:45","description":"Local time; may be on the previous day for early flights"}}},"Booking":{"type":"object","properties":{"reference":{"type":"string","example":"PXT-01234"},"status":{"type":"string","enum":["confirmed","on_request","pending_payment","offered","cancelled"]},"customer_reference":{"type":["string","null"]},"currency":{"type":"string"},"total":{"type":"number"},"paid":{"type":"number"},"payment_url":{"type":["string","null"]},"lead_passenger":{"$ref":"#\/components\/schemas\/LeadPassenger","type":"object","properties":{"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]}}},"offer":{"type":["object","null"],"description":"Only when status is offered: our offer for an on-request booking. Item prices are the offered prices. Accept or decline with POST \/bookings\/{reference}\/offer\/accept|decline.","properties":{"offered_at":{"type":["string","null"],"format":"date-time"},"note":{"type":["string","null"]},"total":{"type":"number"},"currency":{"type":"string"},"accepted_at":{"type":["string","null"],"format":"date-time","description":"Set when accepted but still waiting for card payment"}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["transfer","hourly","airport_service"]},"status":{"type":"string","enum":["scheduled","driver_assigned","on_route","completed","no_show","cancelled"]},"pickup_at":{"type":"string","example":"2026-11-20T14:30"},"timezone":{"type":"string"},"from":{"type":"object"},"to":{"type":["object","null"]},"vehicle_type":{"type":["object","null"]},"price":{"type":["number","null"]},"flight_number":{"type":["string","null"]},"flight_scheduled_at":{"type":["string","null"],"example":"2026-11-20T13:00","description":"Scheduled local time of the flight (departure for trips to the airport, arrival for trips from the airport), filled from flight data when available"},"passengers":{"type":"object","properties":{"adults":{"type":"integer"},"children":{"type":"integer"},"infants":{"type":"integer"}}},"luggage":{"type":"integer","description":"Transfer and hourly items"},"hours":{"type":["number","null"],"description":"Hourly items only"},"service":{"type":"object","description":"Airport service items only","properties":{"name":{"type":"string"},"option":{"type":"string"}}},"cancellation_fee":{"type":"number","description":"Only on items cancelled with a fee (late cancellation)"},"lead_passenger":{"type":"object","description":"Only when this item has a different passenger than the booking lead passenger","properties":{"name":{"type":"string"},"phone":{"type":["string","null"]}}},"passenger_names":{"type":"array","items":{"type":"string"},"description":"Only when more than one passenger is assigned to this item"},"linked_item_id":{"type":["integer","null"],"description":"Airport service items: id of the transfer item it belongs to"},"driver":{"type":["object","null"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"vehicle_plate":{"type":"string"}}}}}},"cancellation":{"type":["object","null"],"properties":{"fee_if_cancelled_now":{"type":"number"}}},"created_at":{"type":"string","format":"date-time"},"test":{"type":"boolean","description":"Sandbox (test key) bookings only"},"cancellation_fee":{"type":"number","description":"Sandbox only: total fee of a cancelled test booking (live bookings report it per item)"}}},"LeadPassenger":{"type":"object","properties":{"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]}}},"Driver":{"type":["object","null"],"description":"Filled when a driver is assigned","properties":{"name":{"type":"string"},"phone":{"type":"string"},"vehicle_plate":{"type":"string"}}},"BookingItem":{"type":"object","description":"One element of Booking.items","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["transfer","hourly","airport_service"]},"status":{"type":"string","enum":["scheduled","driver_assigned","on_route","completed","no_show","cancelled"]},"pickup_at":{"type":"string","example":"2026-11-20T14:30","description":"Local time"},"timezone":{"type":"string"},"from":{"type":"object"},"to":{"type":["object","null"]},"vehicle_type":{"type":["object","null"]},"price":{"type":["number","null"]},"flight_number":{"type":["string","null"]},"flight_scheduled_at":{"type":["string","null"]},"passengers":{"type":"object"},"luggage":{"type":"integer"},"hours":{"type":["number","null"]},"service":{"type":"object"},"cancellation_fee":{"type":"number"},"lead_passenger":{"type":"object"},"passenger_names":{"type":"array","items":{"type":"string"}},"linked_item_id":{"type":["integer","null"]},"driver":{"$ref":"#\/components\/schemas\/Driver"}}},"WebhookEvent":{"type":"object","description":"Body POSTed to your webhook URL (header Paxvel-Signature: t=<unix>,v1=<hex>)","properties":{"id":{"type":"string","example":"evt_3f2a…","description":"Unique event id; use it to ignore duplicates"},"type":{"type":"string","enum":["booking.created","booking.updated","booking.cancelled","ping"]},"env":{"type":"string","enum":["test","live"]},"created_at":{"type":"string","format":"date-time"},"data":{"description":"Booking (for booking.* events) or {message} for ping","oneOf":[{"$ref":"#\/components\/schemas\/Booking"},{"type":"object","properties":{"message":{"type":"string"}}}]}}},"Pagination":{"type":"object","description":"meta of GET \/bookings","properties":{"page":{"type":"integer"},"limit":{"type":"integer","maximum":100},"total":{"type":"integer"}}}}}}