# Update pickup information for shared journeys

> Update the pickup time and details of a shared journey.

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

You will tell the traveller exactly where and when a shared vehicle picks them up. You need an API
key and a journey assigned to your company. This matters if you run shared vehicles, such as shuttle
buses, that collect several travellers on the way to a hub.

## When to use it

A shared journey is one with a shared vehicle category: `SHUTTLE`, `SPEEDY_SHUTTLE`, `EVENT_SHUTTLE`
or `DIRECT_SHUTTLE`. When such a vehicle takes travellers from their addresses to a hub, the driver
makes several stops, and the pickup time and place each traveller asked for are rarely exact. Use
this call to give each traveller the real pickup point and time.

In this guide, Alex Traveller flies home on 5 December. The shared shuttle collects Alex at the hotel
on Herengracht and drives to Schiphol. The journey id is `488219`.

| You send              | Allowed for                                                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `pickupLocation` only | Journeys assigned to you; not limited to shared journeys.                                                                                    |
| `pickupTime`          | Only shared journeys from an address to a hub, in status `CONFIRMED`, `PLANNED` or `DRIVER_UNDERWAY`, with the new time still in the future. |

Send at least one of the two.

## Step 1: Send the pickup point and time

`pickupLocation` needs a `description` and the coordinates; a `title` is optional. `pickupTime` is
the local time at the pickup location, without an offset, like every pickup time.

**Request:** [`PUT /journeys/488219/pickup-info`](https://developers.test.transferz.com/reference/transfer-companies/update-pickup-information)

```bash title="cURL"
curl --request PUT \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488219/pickup-info' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "pickupLocation": {
    "title": "Hotel Example Canal House, main entrance",
    "description": "Wait outside the main entrance on Herengracht. The shuttle stops at the bicycle rack.",
    "latitude": 52.3739,
    "longitude": 4.8865
  },
  "pickupTime": "2026-12-05T07:40:00"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488219/pickup-info", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "pickupLocation": {
      "title": "Hotel Example Canal House, main entrance",
      "description": "Wait outside the main entrance on Herengracht. The shuttle stops at the bicycle rack.",
      "latitude": 52.3739,
      "longitude": 4.8865
    },
    "pickupTime": "2026-12-05T07: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 = """
        {
          "pickupLocation": {
            "title": "Hotel Example Canal House, main entrance",
            "description": "Wait outside the main entrance on Herengracht. The shuttle stops at the bicycle rack.",
            "latitude": 52.3739,
            "longitude": 4.8865
          },
          "pickupTime": "2026-12-05T07:40:00"
        }
        """;

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

var json = """
    {
      "pickupLocation": {
        "title": "Hotel Example Canal House, main entrance",
        "description": "Wait outside the main entrance on Herengracht. The shuttle stops at the bicycle rack.",
        "latitude": 52.3739,
        "longitude": 4.8865
      },
      "pickupTime": "2026-12-05T07: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'
{
  "pickupLocation": {
    "title": "Hotel Example Canal House, main entrance",
    "description": "Wait outside the main entrance on Herengracht. The shuttle stops at the bicycle rack.",
    "latitude": 52.3739,
    "longitude": 4.8865
  },
  "pickupTime": "2026-12-05T07:40:00"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488219/pickup-info');
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 2: Check the journey

The pickup location becomes the journey's meeting point, with type `TRANSFER_COMPANY`. Fetch the
journey to confirm:

**Request:** [`GET /journeys/488219`](https://developers.test.transferz.com/reference/transfer-companies/get-journey)

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488219' \
  --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/488219", {
  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/transfercompanies/journeys/488219"))
        .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/transfercompanies/journeys/488219");
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/488219');
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": 488219,
  "code": "TZ7K4Q-2",
  "pickupTime": { "localTime": "2026-12-05T07:40:00", "timeZone": "Europe/Amsterdam" },
  "vehicleCategory": "SHUTTLE",
  "status": "PLANNED",
  "meetingPoint": {
    "id": 2590,
    "title": "Hotel Example Canal House, main entrance",
    "description": "Wait outside the main entrance on Herengracht. The shuttle stops at the bicycle rack.",
    "latitude": 52.3739,
    "longitude": 4.8865,
    "type": "TRANSFER_COMPANY"
  }
}
```

## How pickup points are stored

Each pickup location is saved as one of your company's meeting points at that hub.

- **With a `title`**, Transferz first looks for one of your meeting points with the same title
  (ignoring upper and lower case) and reuses it. Use the same title for a stop you serve often, such
  as a hotel entrance, and the stop is not created twice. Note that a reused meeting point keeps its
  stored description and coordinates.
- **Without a `title`**, a new meeting point is created for this journey only, named after the
  journey.

Sending the same pickup time again, to the minute, changes nothing.

## Errors

| Status | Code                       | Cause                                                                                                                                                           | What to do                                                                                     |
| ------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `400`  | —                          | Neither `pickupTime` nor `pickupLocation` was sent.                                                                                                             | Send at least one.                                                                             |
| `400`  | `INVALID_REQUEST`          | `pickupLocation` lacks a `description`, `latitude` or `longitude`.                                                                                              | Send all three.                                                                                |
| `400`  | `INVALID_REQUEST`          | Your fleet is not set up for this journey's hub, so no meeting point can be stored ("At least one hub tender is required").                                     | Contact Transferz.                                                                             |
| `400`  | `UNKNOWN`                  | A `pickupTime` was sent for a journey that is not shared, does not go to a hub, is not `CONFIRMED`, `PLANNED` or `DRIVER_UNDERWAY`, or the time is in the past. | Send only `pickupLocation`, or check the journey.                                              |
| `403`  | `INSUFFICIENT_PERMISSIONS` | The journey is not assigned to your company, or the id does not exist.                                                                                          | Check the id.                                                                                  |
| `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 pickup information](https://developers.test.transferz.com/reference/transfer-companies/update-pickup-information) (`PUT /journeys/{id}/pickup-info`)
- [GET Get journey](https://developers.test.transferz.com/reference/transfer-companies/get-journey) (`GET /journeys/{id}`)
