# Report journey progress

> Report driver underway, arrived and in progress, and send the driver's live position.

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

You will tell Transferz where the driver is, at each stage of the journey and continuously on the
road, so the traveller and the partner can follow the car. You need an API key and a journey with a
driver assigned (see [Assign a driver and a vehicle](https://developers.test.transferz.com/guides/transfer-companies/assign-a-driver-and-vehicle)).

There are two ways to do this: your own system calls the API, as described below, or your drivers use
the [Transferz Driver App](#or-let-your-drivers-use-the-driver-app) and you integrate nothing.

## The stages

| Stage                                   | Status                | Call                                                                                                      |
| --------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- |
| The driver leaves for the pickup        | `DRIVER_UNDERWAY`     | [Driver underway](https://developers.test.transferz.com/reference/transfer-companies/set-driver-underway) |
| The driver is at the pickup and waiting | `DRIVER_ARRIVED`      | [Driver arrived](https://developers.test.transferz.com/reference/transfer-companies/set-driver-arrived)   |
| The traveller is on board               | `JOURNEY_IN_PROGRESS` | [In progress](https://developers.test.transferz.com/reference/transfer-companies/set-journey-in-progress) |
| The traveller was dropped off           | `COMPLETED`           | [Complete a journey](https://developers.test.transferz.com/guides/transfer-companies/complete-a-journey)  |

Between the stages, send the driver's position regularly. Each stage call carries a position too.

## Step 1: Driver underway

When the driver sets off for Schiphol, send the status with the driver's current position:

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

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/driver-underway' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "latitude": 52.3462,
  "longitude": 4.9171,
  "recordedAt": "2026-12-01T12:40:00"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/driver-underway", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "latitude": 52.3462,
    "longitude": 4.9171,
    "recordedAt": "2026-12-01T12:40:00"
  }),
});

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 = """
        {
          "latitude": 52.3462,
          "longitude": 4.9171,
          "recordedAt": "2026-12-01T12:40:00"
        }
        """;

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

var json = """
    {
      "latitude": 52.3462,
      "longitude": 4.9171,
      "recordedAt": "2026-12-01T12:40:00"
    }
    """;
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'
{
  "latitude": 52.3462,
  "longitude": 4.9171,
  "recordedAt": "2026-12-01T12:40:00"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/driver-underway');
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
```

`latitude` and `longitude` are required in the body. `recordedAt` is the moment it happened, in
UTC; leave it out to use the time of the request. Transferz then sends the traveller the driver's
details, and you and the partner receive
[`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed).

Status updates are accepted from 48 hours before the pickup time; earlier ones are refused.

## Step 2: Send the position while driving

From driver underway until the drop-off, send the driver's position at short, regular intervals:

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

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/driver-position' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "latitude": 52.3091,
  "longitude": 4.7624,
  "recordedAt": "2026-12-01T13:12:05"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/driver-position", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "latitude": 52.3091,
    "longitude": 4.7624,
    "recordedAt": "2026-12-01T13:12:05"
  }),
});

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 = """
        {
          "latitude": 52.3091,
          "longitude": 4.7624,
          "recordedAt": "2026-12-01T13:12:05"
        }
        """;

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

var json = """
    {
      "latitude": 52.3091,
      "longitude": 4.7624,
      "recordedAt": "2026-12-01T13:12:05"
    }
    """;
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'
{
  "latitude": 52.3091,
  "longitude": 4.7624,
  "recordedAt": "2026-12-01T13:12:05"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/driver-position');
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 partner receives each position as
[`journeyDriverPositionUpdatedEvent`](https://developers.test.transferz.com/reference/webhooks/driver-position-updated), and the traveller sees
the car move. The last position is returned as `lastKnownDriverPosition` by
[Get a journey](https://developers.test.transferz.com/reference/transfer-companies/get-journey).

The API does not enforce an interval. The previous guides asked for a position about every 30 seconds;
the onboarding prototype asked for at most 15 seconds between positions. Sending every 15 seconds meets both.

> **To be confirmed by Transferz:** The required position interval (15 or 30 seconds) is still to be confirmed by Transferz.

## Step 3: Driver arrived

When the driver is at the pickup point and waiting for the traveller:

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

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/driver-arrived' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "latitude": 52.3091,
  "longitude": 4.7624,
  "recordedAt": "2026-12-01T13:12:05"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/driver-arrived", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "latitude": 52.3091,
    "longitude": 4.7624,
    "recordedAt": "2026-12-01T13:12:05"
  }),
});

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 = """
        {
          "latitude": 52.3091,
          "longitude": 4.7624,
          "recordedAt": "2026-12-01T13:12:05"
        }
        """;

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

var json = """
    {
      "latitude": 52.3091,
      "longitude": 4.7624,
      "recordedAt": "2026-12-01T13:12:05"
    }
    """;
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'
{
  "latitude": 52.3091,
  "longitude": 4.7624,
  "recordedAt": "2026-12-01T13:12:05"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/driver-arrived');
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
```

## Step 4: Traveller on board

When the traveller is in the car and you leave for the drop-off:

**Request:** [`PUT /journeys/488213/status/in-progress`](https://developers.test.transferz.com/reference/transfer-companies/set-journey-in-progress)

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/in-progress' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "latitude": 52.3101,
  "longitude": 4.7655,
  "recordedAt": "2026-12-01T13:55:00"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/in-progress", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "latitude": 52.3101,
    "longitude": 4.7655,
    "recordedAt": "2026-12-01T13:55:00"
  }),
});

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 = """
        {
          "latitude": 52.3101,
          "longitude": 4.7655,
          "recordedAt": "2026-12-01T13:55:00"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/in-progress"))
        .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/status/in-progress");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "latitude": 52.3101,
      "longitude": 4.7655,
      "recordedAt": "2026-12-01T13:55:00"
    }
    """;
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'
{
  "latitude": 52.3101,
  "longitude": 4.7655,
  "recordedAt": "2026-12-01T13:55:00"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213/status/in-progress');
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
```

Keep sending positions until the drop-off, then
[complete the journey](https://developers.test.transferz.com/guides/transfer-companies/complete-a-journey).

## Rules worth knowing

- **Send the stages in order.** The API does not check the order: any status that is not final can be
  set from any other. If you send driver arrived after in progress, the journey goes back to
  `DRIVER_ARRIVED`.
- **Repeating a status is harmless.** Sending the status the journey already has returns `204` and
  changes nothing, so retries are safe.
- **Transferz can move the journey on from the position.** When positions show the driver within
  about 100 metres of the pickup while the journey is `DRIVER_UNDERWAY`, Transferz can set
  `DRIVER_ARRIVED` itself; near the drop-off it can set `COMPLETED`. Watch
  [`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed) and do not send an earlier stage
  after a later one has been set.
- **Always include the position.** The body is optional on the stage calls, but Transferz measures
  whether driver underway, driver arrived and in progress came with a position.
- **Assign the driver first.** The Transfer Companies API accepts stage updates and positions for a
  journey without a driver, but the traveller and the partner then have no driver to look for.

> **To be confirmed by Transferz:** Whether Transferz sets `DRIVER_ARRIVED` and `COMPLETED` from positions for every company, and at
> which distance, is still to be confirmed by Transferz.

> **To be confirmed by Transferz:** Whether stage updates for a journey without a driver are meant to be accepted is still to be
> confirmed by Transferz.

## Or let your drivers use the Driver App

The Transferz Driver App runs in the phone's browser; nothing has to be installed. The driver opens
the journey with its `driverCode` (three digits, three letters, three digits, such as `482KQM731`),
or from the link in the SMS sent when you assign the driver with `notifyBySms` set to `true`. The app
sends the stages and the positions for you, so you do not call the endpoints on this page.

> **To be confirmed by Transferz:** The production address of the Driver App, and how a driver signs in to it, are still to be confirmed
> by Transferz. On staging the app is at `https://staging.transferz.taxi/`.

## Errors

| Status | Code                                                                                                                                                                                            | Cause                                                                  | What to do                                                                                      |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `400`  | [JOURNEY_STATUS_CHANGE_NOT_ALLOWED_IF_PICKUP_TIME_TOO_FAR_IN_FUTURE](https://developers.test.transferz.com/reference/errors/journey-status-change-not-allowed-if-pickup-time-too-far-in-future) | The pickup is more than 48 hours away.                                 | Send stage updates on the day of the journey.                                                   |
| `400`  | [STATUS_TRANSITION_NOT_ALLOWED](https://developers.test.transferz.com/reference/errors/status-transition-not-allowed)                                                                           | The journey is completed or cancelled.                                 | Stop sending updates. If Transferz completed it from the position, there is nothing left to do. |
| `400`  | —                                                                                                                                                                                               | `latitude` or `longitude` is missing from a body you sent.             | Send both.                                                                                      |
| `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 Update status to 'driver underway'](https://developers.test.transferz.com/reference/transfer-companies/set-driver-underway) (`PUT /journeys/{id}/status/driver-underway`)
- [PUT Update status to 'driver arrived'](https://developers.test.transferz.com/reference/transfer-companies/set-driver-arrived) (`PUT /journeys/{id}/status/driver-arrived`)
- [PUT Update status to 'in progress'](https://developers.test.transferz.com/reference/transfer-companies/set-journey-in-progress) (`PUT /journeys/{id}/status/in-progress`)
- [PUT Update driver position](https://developers.test.transferz.com/reference/transfer-companies/update-driver-position) (`PUT /journeys/{id}/driver-position`)

### Walk-through steps

- [Share journey tracking](https://developers.test.transferz.com/walkthrough/transfer-company/share-journey-tracking)
