Paxvel Hub API v1.0.0

Base URL:https://paxvelhub.com/api/v1 OpenAPI 3.1

Quote and book airport transfers, hourly chauffeur services and airport services (fast track, lounge, meet & assist).

Authentication: 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.

Prices 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.

Errors: {"error": {"code", "message", "details"}, "request_id"}. Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After on 429.

Webhooks: 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.

Check your key

GET/ping

Responses

200OK
401Error
403Error
422Error
429Error

Example request Try it →

curl "https://paxvelhub.com/api/v1/ping" \
  -H "Authorization: Bearer $PAXVEL_KEY"

Vehicle types

GET/vehicle-types

Responses

200OK
401Error
403Error
422Error
429Error

Example request Try it →

curl "https://paxvelhub.com/api/v1/vehicle-types" \
  -H "Authorization: Bearer $PAXVEL_KEY"

Search airports, hotels and other locations

GET/locations

Parameters

qquery · stringrequired
typequery · string: one of: airport, hotel, port, station, other
countryquery · string: e.g. TR
limitquery · integer: max 50

Responses

200OK
401Error
403Error
422Error
429Error

Example request Try it →

curl "https://paxvelhub.com/api/v1/locations?q=antalya" \
  -H "Authorization: Bearer $PAXVEL_KEY"

Get prices (transfer or hourly)

POST/quotes

Request body

servicestring: one of: transfer, hourly · default "transfer"
fromobjectrequired: One of: location_id, iata, or lat + lng + address.
location_idinteger: e.g. 12
iatastring: e.g. AYT
latnumber: e.g. 36.862
lngnumber: e.g. 31.056
addressstring: max 300 chars · e.g. Regnum Carya, Belek
countrystring: e.g. TR
toobject: One of: location_id, iata, or lat + lng + address.
location_idinteger: e.g. 12
iatastring: e.g. AYT
latnumber: e.g. 36.862
lngnumber: e.g. 31.056
addressstring: max 300 chars · e.g. Regnum Carya, Belek
countrystring: e.g. TR
datestring (date)required: e.g. 2026-11-20
timestringrequired: Local time at pick-up — e.g. 14:30
hoursnumber: Hourly service only (1–48)
passengersobject
adultsinteger: default 1
childreninteger
infantsinteger
luggageinteger
instant_onlyboolean: Return only offers that can be confirmed instantly (confirmation = instant). Always on when your account is set to instant confirmation only. — default false

Responses

200OK
401Error
403Error
422Error
429Error

Example request Try it →

curl -X POST "https://paxvelhub.com/api/v1/quotes" \
  -H "Authorization: Bearer $PAXVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
        "location_id": 12,
        "iata": "AYT",
        "lat": 36.862,
        "lng": 31.056,
        "address": "Regnum Carya, Belek",
        "country": "TR"
    },
    "date": "2026-11-20",
    "time": "14:30",
    "passengers": {
        "adults": 1
    }
}'

Suggested pick-up time from a flight number

POST/flights/pickup-time

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.

Request body

flight_numberstringrequired: e.g. TK1937
datestring (date)required: Local date of the transfer — e.g. 2026-11-20
fromobjectrequired: One of: location_id, iata, or lat + lng + address.
location_idinteger: e.g. 12
iatastring: e.g. AYT
latnumber: e.g. 36.862
lngnumber: e.g. 31.056
addressstring: max 300 chars · e.g. Regnum Carya, Belek
countrystring: e.g. TR
toobjectrequired: One of: location_id, iata, or lat + lng + address.
location_idinteger: e.g. 12
iatastring: e.g. AYT
latnumber: e.g. 36.862
lngnumber: e.g. 31.056
addressstring: max 300 chars · e.g. Regnum Carya, Belek
countrystring: e.g. TR

Responses

200OK
404Flight not found (flight_not_found)
503Flight data not available (flight_data_unavailable)
401Error
403Error
422Error
429Error

Example request Try it →

curl -X POST "https://paxvelhub.com/api/v1/flights/pickup-time" \
  -H "Authorization: Bearer $PAXVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flight_number": "TK1937",
    "date": "2026-11-20",
    "from": {
        "location_id": 12,
        "iata": "AYT",
        "lat": 36.862,
        "lng": 31.056,
        "address": "Regnum Carya, Belek",
        "country": "TR"
    },
    "to": {
        "location_id": 12,
        "iata": "AYT",
        "lat": 36.862,
        "lng": 31.056,
        "address": "Regnum Carya, Belek",
        "country": "TR"
    }
}'

Airport services with prices

GET/airport-services

Parameters

airportquery · stringrequired: e.g. IST
datequery · string (date)required
timequery · string: e.g. 09:30
directionquery · string: one of: arrival, departure
adultsquery · integer
childrenquery · integer
infantsquery · integer

Responses

200OK
401Error
403Error
422Error
429Error

Example request Try it →

curl "https://paxvelhub.com/api/v1/airport-services?airport=IST&date=2026-11-20" \
  -H "Authorization: Bearer $PAXVEL_KEY"

Create a booking from offers

POST/bookings

Parameters

Idempotency-Keyheader · string

Request body

itemsarray of object
offer_idstringrequired
flight_numberstring: e.g. TK2412
notestring
servicesarray of object
offer_idstringrequired
flight_numberstring
atstring: e.g. 2026-11-20 09:30
for_iteminteger: Index (0-based) in items of the transfer this service belongs to. Optional.
lead_passengerobjectrequired
namestringrequired
phonestring
emailstring
passengersarray of object
namestring
typestring: one of: adult, child, infant
referencestring: Your own booking reference — max 80 chars
notestring: max 2000 chars
instant_onlyboolean: 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. — default false

Responses

201Created
409Error
410Error
401Error
403Error
422Error
429Error

Example request Try it →

curl -X POST "https://paxvelhub.com/api/v1/bookings" \
  -H "Authorization: Bearer $PAXVEL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-booking-1" \
  -d '{
    "lead_passenger": {
        "name": "string",
        "phone": "string",
        "email": "string"
    },
    "passengers": [
        {
            "name": "string"
        }
    ]
}'

List bookings

GET/bookings

Parameters

fromquery · string (date)
toquery · string (date)
referencequery · string
pagequery · integer
limitquery · integer: max 100

Responses

200OK
401Error
403Error
422Error
429Error

Example request Try it →

curl "https://paxvelhub.com/api/v1/bookings" \
  -H "Authorization: Bearer $PAXVEL_KEY"

Get a booking

GET/bookings/{reference}

Parameters

referencepath · stringrequired: e.g. PXT-01234

Responses

200OK
404Error
401Error
403Error
422Error
429Error

Example request Try it →

curl "https://paxvelhub.com/api/v1/bookings/PXT-01234" \
  -H "Authorization: Bearer $PAXVEL_KEY"

Cancel a booking (fee per cancellation policy)

POST/bookings/{reference}/cancel

Parameters

referencepath · stringrequired

Request body

reasonstring

Responses

200OK
404Error
409Error
401Error
403Error
422Error
429Error

Example request Try it →

curl -X POST "https://paxvelhub.com/api/v1/bookings/PXT-01234/cancel" \
  -H "Authorization: Bearer $PAXVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Accept the offer on an on-request booking (status offered → confirmed; card accounts get a payment_url and are confirmed after payment)

POST/bookings/{reference}/offer/accept

Parameters

referencepath · stringrequired

Responses

200OK
404Error
409Error
401Error
403Error
422Error
429Error

Example request Try it →

curl -X POST "https://paxvelhub.com/api/v1/bookings/PXT-01234/offer/accept" \
  -H "Authorization: Bearer $PAXVEL_KEY"

Decline the offer on an on-request booking (booking is cancelled free of charge)

POST/bookings/{reference}/offer/decline

Parameters

referencepath · stringrequired

Request body

reasonstring: max 500 chars

Responses

200OK
404Error
409Error
401Error
403Error
422Error
429Error

Example request Try it →

curl -X POST "https://paxvelhub.com/api/v1/bookings/PXT-01234/offer/decline" \
  -H "Authorization: Bearer $PAXVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Test only: simulate a status change

POST/test/bookings/{reference}/simulate

Parameters

referencepath · stringrequired: e.g. TEST-1A2B3C4

Request body

eventstring: one of: payment_completed, confirmed, driver_assigned, on_route, completed, no_show, on_request, offered

Responses

200OK
404Error
409Error
401Error
403Error
422Error
429Error

Example request Try it →

curl -X POST "https://paxvelhub.com/api/v1/test/bookings/TEST-1A2B3C4/simulate" \
  -H "Authorization: Bearer $PAXVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Send a ping webhook to your URL now

POST/test/webhook

Responses

200OK
401Error
403Error
422Error
429Error

Example request Try it →

curl -X POST "https://paxvelhub.com/api/v1/test/webhook" \
  -H "Authorization: Bearer $PAXVEL_KEY"

VehicleType

idinteger
codestring
namestring
max_passengersinteger
max_luggageinteger
image_urlstring
modelsstring | null: Example models, e.g. "Mercedes Vito or similar"
free_waiting_minutesinteger | null: Free waiting time included in the price

AirportService

idinteger
typestring: e.g. fast_track
namestring
airportstring: e.g. IST
terminalstring | null
meeting_pointstring | null
descriptionstring | null
locationstring | null: Directions inside the airport
zonestring | null: one of: airside, landside, ``
opening_hoursstring | null
max_stay_hoursnumber | null
conditionsarray of string
featuresarray of string: Keys such as wifi, shower, alcohol, aircon, accessible
children_allowedboolean
infants_allowedboolean
photosarray of string
optionsarray of object
offer_idstring
namestring
duration_hoursnumber | null
directionstring | null: any = valid for both directions — one of: any, arrival, departure, transit, ``
pricenumber | null
currencystring
expires_atstring (date-time)

Location

idinteger
typestring
iatastring
namestring
citystring
countrystring
latnumber
lngnumber

Offer

offer_idstring
vehicle_typeVehicleType: Offers carry id, code, name, max_passengers and max_luggage; see /vehicle-types for the full card
pricenumber | null: null = price on request
currencystring
confirmationstring: one of: instant, on_request
free_cancellation_hoursinteger
expires_atstring (date-time)

Quote

servicestring
currencystring
distance_kmnumber | null
timezonestring
out_of_service_areaboolean
instant_onlyboolean: True when only instantly confirmable offers are returned.
offersarray of Offer
airport_servicesarray of ServiceHint: Airport services (fast track, lounge, meet & greet) available at the airport ends of this transfer. Empty for hourly quotes.

ServiceHint

airportstring: e.g. AYT
directionstring: one of: arrival, departure
countinteger
typesarray of string
fromobject | null
suggested_atstring | null: Suggested service time (airport local), departure: estimated arrival at the airport
searchstring: GET path that lists these services with offer_id values

PickupTime

flight_numberstring: e.g. TK1937
airlinestring | null
departureobject
airportstring | null: e.g. IST
scheduled_atstring | null: Local time — e.g. 2026-11-20T07:40
terminalstring | null
arrivalobject
airportstring | null
scheduled_atstring | null
terminalstring | null
domesticboolean | null
tripstring | null: one of: to_airport, from_airport, ``
airport_matchboolean: false when the flight does not use the airport of this trip
airport_before_minutesinteger | null
drive_minutesinteger | null
rush_minutesinteger | null
suggested_pickup_atstring | null: Local time; may be on the previous day for early flights — e.g. 2026-11-20T03:45

Booking

referencestring: e.g. PXT-01234
statusstring: one of: confirmed, on_request, pending_payment, offered, cancelled
customer_referencestring | null
currencystring
totalnumber
paidnumber
payment_urlstring | null
lead_passengerLeadPassenger
offerobject | null: 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.
itemsarray of object
idinteger
typestring: one of: transfer, hourly, airport_service
statusstring: one of: scheduled, driver_assigned, on_route, completed, no_show, cancelled
pickup_atstring: e.g. 2026-11-20T14:30
timezonestring
fromobject
toobject | null
vehicle_typeobject | null
pricenumber | null
flight_numberstring | null
flight_scheduled_atstring | null: Scheduled local time of the flight (departure for trips to the airport, arrival for trips from the airport), filled from flight data when available — e.g. 2026-11-20T13:00
passengersobject
adultsinteger
childreninteger
infantsinteger
luggageinteger: Transfer and hourly items
hoursnumber | null: Hourly items only
serviceobject: Airport service items only
namestring
optionstring
cancellation_feenumber: Only on items cancelled with a fee (late cancellation)
lead_passengerobject: Only when this item has a different passenger than the booking lead passenger
namestring
phonestring | null
passenger_namesarray of string: Only when more than one passenger is assigned to this item
linked_item_idinteger | null: Airport service items: id of the transfer item it belongs to
driverobject | null
cancellationobject | null
created_atstring (date-time)
testboolean: Sandbox (test key) bookings only
cancellation_feenumber: Sandbox only: total fee of a cancelled test booking (live bookings report it per item)

LeadPassenger

namestring | null
phonestring | null
emailstring | null

Driver

namestring
phonestring
vehicle_platestring

BookingItem

idinteger
typestring: one of: transfer, hourly, airport_service
statusstring: one of: scheduled, driver_assigned, on_route, completed, no_show, cancelled
pickup_atstring: Local time — e.g. 2026-11-20T14:30
timezonestring
fromobject
toobject | null
vehicle_typeobject | null
pricenumber | null
flight_numberstring | null
flight_scheduled_atstring | null
passengersobject
luggageinteger
hoursnumber | null
serviceobject
cancellation_feenumber
lead_passengerobject
passenger_namesarray of string
linked_item_idinteger | null
driverDriver: Filled when a driver is assigned

WebhookEvent

idstring: Unique event id; use it to ignore duplicates — e.g. evt_3f2a…
typestring: one of: booking.created, booking.updated, booking.cancelled, ping
envstring: one of: test, live
created_atstring (date-time)
dataobject: Booking (for booking.* events) or {message} for ping

Pagination

pageinteger
limitinteger: max 100
totalinteger

Paxvel Hub API v1.0.0

General

Check your key

Responses

Vehicle types

Responses

Search airports, hotels and other locations

Parameters

Responses

Booking

Get prices (transfer or hourly)

Request body

Responses

Suggested pick-up time from a flight number

Request body

Responses

Airport services with prices

Parameters

Responses

Create a booking from offers

Parameters

Request body

Responses

List bookings

Parameters

Responses

Get a booking

Parameters

Responses

Cancel a booking (fee per cancellation policy)

Parameters

Request body

Responses

Accept the offer on an on-request booking (status offered → confirmed; card accounts get a payment_url and are confirmed after payment)

Parameters

Responses

Decline the offer on an on-request booking (booking is cancelled free of charge)

Parameters

Request body

Responses

Testing

Test only: simulate a status change

Parameters

Request body

Responses

Send a ping webhook to your URL now

Responses

Objects

VehicleType

AirportService

Location

Offer

Quote

ServiceHint

PickupTime

Booking

LeadPassenger

Driver

BookingItem

WebhookEvent

Pagination