# Assign a driver and a vehicle

> Assign, change or remove the driver and vehicle of a journey.

Section: Transfer companies · Last updated: 2026-11-15

You will assign a driver and then a vehicle to a journey, and change or remove them when plans
change. You need an API key and a journey assigned to your company (see
[Receive journeys by webhook](https://developers.test.transferz.com/guides/transfer-companies/receive-journeys-by-webhook)).

The partner and the traveller see the driver's name and phone number and the vehicle's licence
plate, so they know whom and what to look for.

## Step 1: Assign the driver

Send the driver's name and mobile number. The number must be in international format: a plus sign
followed by digits only, no spaces or dashes.

**Request:** [`PUT /journeys/488213/assign-driver`](https://developers.test.transferz.com/reference/transfer-companies/assign-driver)

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "name": "Jordan Driver",
  "phoneNumber": "+447700900456",
  "notifyBySms": true,
  "reassign": false
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "name": "Jordan Driver",
    "phoneNumber": "+447700900456",
    "notifyBySms": true,
    "reassign": false
  }),
});

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 = """
        {
          "name": "Jordan Driver",
          "phoneNumber": "+447700900456",
          "notifyBySms": true,
          "reassign": false
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("PUT", 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.Put, "https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "name": "Jordan Driver",
      "phoneNumber": "+447700900456",
      "notifyBySms": true,
      "reassign": false
    }
    """;
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'
{
  "name": "Jordan Driver",
  "phoneNumber": "+447700900456",
  "notifyBySms": true,
  "reassign": false
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    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 (204):**

```http
HTTP/1.1 204 No Content
```

The journey moves from `CONFIRMED` to `PLANNED`, and you receive
[`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed). A journey that does not end at a
hub, such as this one from Schiphol into the city, moves to `PLANNED` only once it also has a meeting
point; until then it stays `CONFIRMED`. With `notifyBySms` set to `true`, the
driver receives the journey details by SMS. Both `notifyBySms` and `reassign` default to `false`.

The driver does not need an account. The phone number identifies the driver; if your drivers use the
Transferz Driver App, see [Report journey progress](https://developers.test.transferz.com/guides/transfer-companies/report-journey-progress#or-let-your-drivers-use-the-driver-app).

## Step 2: Assign the vehicle

Assign the driver first. The licence plate is required; make, model and series are optional but help
the traveller recognise the car.

**Request:** [`PUT /journeys/488213/assign-vehicle`](https://developers.test.transferz.com/reference/transfer-companies/assign-vehicle)

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-vehicle' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "licensePlate": "TZ-123-X",
  "make": "Toyota",
  "model": "Corolla Touring",
  "series": "Hybrid",
  "reassign": false
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-vehicle", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "licensePlate": "TZ-123-X",
    "make": "Toyota",
    "model": "Corolla Touring",
    "series": "Hybrid",
    "reassign": false
  }),
});

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 = """
        {
          "licensePlate": "TZ-123-X",
          "make": "Toyota",
          "model": "Corolla Touring",
          "series": "Hybrid",
          "reassign": false
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-vehicle"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("PUT", 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.Put, "https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-vehicle");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "licensePlate": "TZ-123-X",
      "make": "Toyota",
      "model": "Corolla Touring",
      "series": "Hybrid",
      "reassign": false
    }
    """;
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'
{
  "licensePlate": "TZ-123-X",
  "make": "Toyota",
  "model": "Corolla Touring",
  "series": "Hybrid",
  "reassign": false
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-vehicle');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    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 (204):**

```http
HTTP/1.1 204 No Content
```

[Get a journey](https://developers.test.transferz.com/reference/transfer-companies/get-journey) now shows both:

```json
{
  "driver": { "id": 77015, "name": "Jordan Driver", "phoneNumber": "+447700900456" },
  "vehicle": {
    "id": 88120,
    "licensePlate": "TZ-123-X",
    "makeName": "Toyota",
    "modelName": "Corolla Touring",
    "seriesName": "Hybrid"
  }
}
```

## Change the driver or the vehicle

To replace an assigned driver or vehicle, send the assignment again with `reassign` set to `true`. The
old one is removed and the new one assigned in one call. With `notifyBySms`, both the old and the new
driver are told by SMS.

**Request:** [`PUT /journeys/488213/assign-driver`](https://developers.test.transferz.com/reference/transfer-companies/assign-driver)

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "name": "Sam Driver",
  "phoneNumber": "+447700900789",
  "notifyBySms": true,
  "reassign": true
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "name": "Sam Driver",
    "phoneNumber": "+447700900789",
    "notifyBySms": true,
    "reassign": true
  }),
});

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 = """
        {
          "name": "Sam Driver",
          "phoneNumber": "+447700900789",
          "notifyBySms": true,
          "reassign": true
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("PUT", 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.Put, "https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "name": "Sam Driver",
      "phoneNumber": "+447700900789",
      "notifyBySms": true,
      "reassign": true
    }
    """;
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'
{
  "name": "Sam Driver",
  "phoneNumber": "+447700900789",
  "notifyBySms": true,
  "reassign": true
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/assign-driver');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    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 (204):**

```http
HTTP/1.1 204 No Content
```

Without `reassign`, assigning a second driver or vehicle fails.

## Remove the driver or the vehicle

Removing the driver also removes the vehicle, and moves the journey back to `CONFIRMED`, also when the
driver was already underway, had arrived or had the traveller on board. The driver is told by SMS
unless you send `notifyBySms=false`:

**Request:** [`PUT /journeys/488213/unassign-driver`](https://developers.test.transferz.com/reference/transfer-companies/unassign-driver)

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/unassign-driver?notifyBySms=false' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/unassign-driver?notifyBySms=false", {
  method: "PUT",
  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/transfercompanies/journeys/488213/unassign-driver?notifyBySms=false"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("PUT", 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.Put, "https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/unassign-driver?notifyBySms=false");
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/transfercompanies/journeys/488213/unassign-driver?notifyBySms=false');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    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 (204):**

```http
HTTP/1.1 204 No Content
```

To remove only the vehicle, for example before you assign another car to the same driver:

**Request:** [`PUT /journeys/488213/unassign-vehicle`](https://developers.test.transferz.com/reference/transfer-companies/unassign-vehicle)

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/unassign-vehicle' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/unassign-vehicle", {
  method: "PUT",
  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/transfercompanies/journeys/488213/unassign-vehicle"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("PUT", 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.Put, "https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/unassign-vehicle");
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/transfercompanies/journeys/488213/unassign-vehicle');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    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 (204):**

```http
HTTP/1.1 204 No Content
```

Removing the vehicle of a `PLANNED` journey also moves it back to `CONFIRMED`; it returns to `PLANNED`
when you assign a vehicle again. Expect the matching
[`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed) events.

## Errors

| Status | Code                                                                                                                                        | Cause                                                                                   | What to do                                                                                     |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `400`  | —                                                                                                                                           | `name` or `phoneNumber` is missing, or the phone number is not in international format. | Send `+` and digits only, such as `+447700900456`.                                             |
| `400`  | [JOURNEY_ALREADY_ASSIGNED_TO_OTHER_DRIVER](https://developers.test.transferz.com/reference/errors/journey-already-assigned-to-other-driver) | Another driver is assigned and `reassign` is `false`.                                   | Send `reassign: true`, or unassign first.                                                      |
| `400`  | [DRIVER_NOT_ASSIGNED](https://developers.test.transferz.com/reference/errors/driver-not-assigned)                                           | You assigned a vehicle before a driver.                                                 | Assign the driver first.                                                                       |
| `400`  | [VEHICLE_ALREADY_ASSIGNED](https://developers.test.transferz.com/reference/errors/vehicle-already-assigned)                                 | A vehicle is assigned and `reassign` is `false`.                                        | Send `reassign: true`, or unassign the vehicle first.                                          |
| `400`  | `UNKNOWN`                                                                                                                                   | The journey is completed or cancelled ("already in a final state").                     | Do not change finished journeys.                                                               |
| `403`  | `INSUFFICIENT_PERMISSIONS`                                                                                                                  | The journey is not assigned to your company, or the id does not exist.                  | Check the id; the journey may have been unassigned from you.                                   |
| `401`  | —                                                                                                                                           | The API key is missing, wrong or expired.                                               | See [Authentication](https://developers.test.transferz.com/guides/get-started/authentication). |

The error format is described in [Errors](https://developers.test.transferz.com/guides/essentials/errors).

## Related

### Endpoints

- [PUT Assign to driver](https://developers.test.transferz.com/reference/transfer-companies/assign-driver) (`PUT /journeys/{id}/assign-driver`)
- [PUT Assign vehicle](https://developers.test.transferz.com/reference/transfer-companies/assign-vehicle) (`PUT /journeys/{id}/assign-vehicle`)
- [PUT Unassign driver](https://developers.test.transferz.com/reference/transfer-companies/unassign-driver) (`PUT /journeys/{id}/unassign-driver`)
- [PUT Unassign vehicle](https://developers.test.transferz.com/reference/transfer-companies/unassign-vehicle) (`PUT /journeys/{id}/unassign-vehicle`)

### Walk-through steps

- [Assign a driver](https://developers.test.transferz.com/walkthrough/transfer-company/assign-a-driver)
- [Assign a vehicle](https://developers.test.transferz.com/walkthrough/transfer-company/assign-a-vehicle)
