Skip to content

Create a booking

Turn a quote into a booking with traveller details and your own reference.

Updated · 3 min read

You will book the quote the traveller chose, with their details and your own order reference. You need a quote id that has not expired (see Request quotes), the ids of any add-ons the traveller picked, and the booker's and traveller's details.

Step 1: Collect the booker and traveller details

A booking has one booker and, per journey, one traveller:

  • The booker places the booking: the traveller themselves, a colleague or a travel agent.
  • The traveller takes the trip. The driver sees the traveller's name and phone number, and the flight number lets Transferz track the flight.
FieldRequiredNotes
booker.email, traveller.emailYes6 to 255 characters
firstName, lastNameNoSend them: the driver needs a name
phoneNoInternational format with country code, for example +447700900123
traveller.flightNumberNoFor airport journeys; or trainNumber or shipName
traveller.meetAndGreetSignTextNoThe name on the driver's sign
traveller.driverCommentsNoNotes for the driver, such as extra luggage
languageIsoCodeNoTwo letters, for example en
traveller.residenceCountryCodeNoTwo letters, for example GB
booker.companyName, booker.referenceNoFor business bookings

Only the email addresses are required by the API, but a journey with missing details can be held for a check by Transferz (AWAITING_APPROVAL) and is harder for the driver. Send everything you have.

Step 2: Create the booking

Send the quote ids with the traveller details to Create booking. partnerReference (required) is your own order reference; it is shown in the Transferz back office. travelIntent is BUSINESS, LEISURE or UNKNOWN.

This example books the sedan from the quote request with meet and greet:

POST/bookingsReference
Sign in to fill in your staging key. Sign in
curl --request POST \  --url 'https://warpdrive.staging.transferz.com/partners/bookings' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY' \  --data '{  "booker": {    "firstName": "Alex",    "lastName": "Traveller",    "email": "alex.traveller@example.com",    "phone": "+447700900123",    "languageIsoCode": "en"  },  "quotes": [    {      "quoteId": 7731201,      "traveller": {        "firstName": "Alex",        "lastName": "Traveller",        "email": "alex.traveller@example.com",        "phone": "+447700900123",        "meetAndGreetSignText": "Alex Traveller",        "driverComments": "Two suitcases and a stroller.",        "flightNumber": "TZ1234",        "languageIsoCode": "en",        "residenceCountryCode": "GB"      },      "travelAddons": [        {          "quoteTravelAddonId": 77312011,          "amount": 1        }      ]    }  ],  "partnerReference": "ORDER-10023",  "travelIntent": "LEISURE"}'
Response 201
{  "id": 312840,  "code": "TZ7K4QM",  "partnerReference": "ORDER-10023",  "partnerId": 4100,  "travelIntent": "LEISURE",  "bookerInfo": {    "firstName": "Alex",    "lastName": "Traveller",    "email": "alex.traveller@example.com",    "phone": "+447700900123",    "languageIsoCode": "en"  },  "journeys": [    {      "id": 488213,      "code": "TZ7K4QM-1",      "quoteId": 7731201,      "vehicleCategory": "SEDAN",      "pickupTimeAdjustmentMethod": "FLIGHT_TRACKING",      "origin": { "resolvedAddress": "Amsterdam Airport Schiphol (AMS)", "hub": true, "iataCode": "AMS" },      "destination": { "resolvedAddress": "Herengracht 182, 1016 BR Amsterdam, Netherlands", "hub": false },      "pickup": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" },      "transferCompany": null,      "driver": null,      "meetingPoint": null,      "approxDurationAndDistance": { "distance": 19.8, "distanceUnit": "KILOMETER", "durationInSeconds": 1560 },      "traveller": {        "firstName": "Alex",        "lastName": "Traveller",        "email": "alex.traveller@example.com",        "phone": "+447700900123",        "meetAndGreetSignText": "Alex Traveller",        "driverComments": "Two suitcases and a stroller.",        "flightNumber": "TZ1234",        "languageIsoCode": "en",        "residenceCountryCode": "GB"      },      "travelAddons": [{ "type": "MEET_GREET", "amount": 1 }],      "status": "NOT_PAID",      "cancellationDetails": {        "cancellable": true,        "freeCancellationUntil": "2026-11-30T14:30:00",        "freeCancellationWindowHours": 24      },      "priceSummary": { "price": 72, "priceVat": 5.94, "commission": 7.2, "commissionVat": 0, "currency": "EUR" },      "customerServiceInfo": { "supportPhoneNumber": "+442079460100" },      "travellerAppUrl": "https://traveller.example.com/j/TZ7K4QM-1"    }  ]}

The response is 201 Created, with the booking and one journey per quote. Every journey is NOT_PAID.

Add-ons. For each add-on, send the id from the quote's availableTravelAddons as quoteTravelAddonId, with an amount of at most maxAllowed. Child, baby and booster seats together must also fit combinedSeatBasedAddonCapacity.

Return trips. Put both quotes in quotes, each with its own traveller details (repeat them if they are the same, and give each its own flight number). The booking then has two journeys.

Step 3: Store the ids

Store the booking id and every journey id with your order. You need them for every later call and to match webhook events, and there is no call to list or search bookings. Show the traveller the booking code or the journey code, not the ids.

To read the booking again, call Get booking:

GET/bookings/312840Reference
Sign in to fill in your staging key. Sign in
curl --request GET \  --url 'https://warpdrive.staging.transferz.com/partners/bookings/312840' \  --header 'Accept: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY'
Response 200
{  "id": 312840,  "code": "TZ7K4QM",  "partnerReference": "ORDER-10023",  "journeys": [{ "id": 488213, "code": "TZ7K4QM-1", "status": "NOT_PAID" }]}

Pay next

A booking is not processed until it is paid: no transfer company is asked and no driver comes. Continue with Pay for a booking.

Errors

ProblemCauseWhat to do
400 with QUOTE_EXPIREDThe quote's expires time has passed.Request new quotes and book the new quote id.
400 with QUOTE_CAPACITY_CONSTRAINTMore passengers or luggage than the quoted vehicle carries.Request quotes with the right party and choose a vehicle that fits.
400 with QUOTE_PERMISSIONThe quotes were requested for different partner accounts.Book quotes requested with the same account.
400 with JOURNEY_TRAVEL_ADDON_MAX_ALLOWED_AMOUNT_EXCEEDEDAn add-on amount is above its maxAllowed.Stay within maxAllowed and combinedSeatBasedAddonCapacity.
400 with a field, such as partnerReferenceA required field is missing, or a value is too short or long.Fix the field. See validation errors.
403 with INSUFFICIENT_PERMISSIONS from Get bookingThe booking belongs to another partner.Check the booking id and the API key.
404 from Get bookingNo booking with this id in this environment.Check the id and that you are on the right environment.

Next steps

Was this helpful?