# Create a booking

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

Section: Partners · Last updated: 2026-11-15

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](https://developers.test.transferz.com/guides/partners/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](https://developers.test.transferz.com/reference/partners/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:

**Request:** [`POST /bookings`](https://developers.test.transferz.com/reference/partners/create-booking)

```bash title="cURL"
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"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/partners/bookings", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "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"
  }),
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    String body = """
        {
          "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"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/partners/bookings"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://warpdrive.staging.transferz.com/partners/bookings");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "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"
    }
    """;
request.Content = new StringContent(json, Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$body = <<<'JSON'
{
  "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"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/partners/bookings');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (201):**

```json
{
  "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](https://developers.test.transferz.com/reference/partners/get-booking):

**Request:** [`GET /bookings/312840`](https://developers.test.transferz.com/reference/partners/get-booking)

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/partners/bookings/312840' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/partners/bookings/312840", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/partners/bookings/312840"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://warpdrive.staging.transferz.com/partners/bookings/312840");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('https://warpdrive.staging.transferz.com/partners/bookings/312840');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
{
  "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](https://developers.test.transferz.com/guides/partners/pay-for-a-booking).

> **To be confirmed by Transferz:** What happens to a booking that is never paid, and after how long, is still to be confirmed by
> Transferz.

## Errors

| Problem                                                                                                                                                                | Cause                                                         | What to do                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400` with [QUOTE_EXPIRED](https://developers.test.transferz.com/reference/errors/quote-expired)                                                                       | The quote's `expires` time has passed.                        | Request new quotes and book the new quote id.                                                                                   |
| `400` with [QUOTE_CAPACITY_CONSTRAINT](https://developers.test.transferz.com/reference/errors/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](https://developers.test.transferz.com/reference/errors/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](https://developers.test.transferz.com/reference/errors/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](https://developers.test.transferz.com/guides/essentials/errors#validation-partners-api). |
| `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](https://developers.test.transferz.com/guides/partners/pay-for-a-booking).
- [Follow a journey](https://developers.test.transferz.com/guides/partners/follow-a-journey) once it is paid.

## Related

### Endpoints

- [POST Create booking](https://developers.test.transferz.com/reference/partners/create-booking) (`POST /bookings`)
- [GET Get booking by id](https://developers.test.transferz.com/reference/partners/get-booking) (`GET /bookings/{id}`)

### Walk-through steps

- [Book the trip](https://developers.test.transferz.com/walkthrough/partner/book-the-trip)
