Create a booking
Turn a quote into a booking with traveller details and your own reference.
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.
| Field | Required | Notes |
|---|---|---|
booker.email, traveller.email | Yes | 6 to 255 characters |
firstName, lastName | No | Send them: the driver needs a name |
phone | No | International format with country code, for example +447700900123 |
traveller.flightNumber | No | For airport journeys; or trainNumber or shipName |
traveller.meetAndGreetSignText | No | The name on the driver's sign |
traveller.driverComments | No | Notes for the driver, such as extra luggage |
languageIsoCode | No | Two letters, for example en |
traveller.residenceCountryCode | No | Two letters, for example GB |
booker.companyName, booker.reference | No | For 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:
/bookingsReferencecurl --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"}'{ "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:
/bookings/312840Referencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/partners/bookings/312840' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'{ "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
| Problem | Cause | What to do |
|---|---|---|
400 with QUOTE_EXPIRED | The quote's expires time has passed. | Request new quotes and book the new quote id. |
400 with QUOTE_CAPACITY_CONSTRAINT | More passengers or luggage than the quoted vehicle carries. | Request quotes with the right party and choose a vehicle that fits. |
400 with QUOTE_PERMISSION | The quotes were requested for different partner accounts. | Book quotes requested with the same account. |
400 with JOURNEY_TRAVEL_ADDON_MAX_ALLOWED_AMOUNT_EXCEEDED | An add-on amount is above its maxAllowed. | Stay within maxAllowed and combinedSeatBasedAddonCapacity. |
400 with a field, such as partnerReference | A required field is missing, or a value is too short or long. | Fix the field. See validation errors. |
403 with INSUFFICIENT_PERMISSIONS from Get booking | The booking belongs to another partner. | Check the booking id and the API key. |
404 from Get booking | No booking with this id in this environment. | Check the id and that you are on the right environment. |
Next steps
- Pay for a booking.
- Follow a journey once it is paid.
Related
Walk-through