Skip to content

Update pickup information for shared journeys

Update the pickup time and details of a shared journey.

Updated · 2 min read

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 sendAllowed for
pickupLocation onlyJourneys assigned to you; not limited to shared journeys.
pickupTimeOnly 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.

PUT/journeys/488219/pickup-infoReference
Sign in to fill in your staging key. Sign in
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"}'
Response 204
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:

GET/journeys/488219Reference
Sign in to fill in your staging key. Sign in
curl --request GET \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488219' \  --header 'Accept: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY'
Response 200
{  "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

StatusCodeCauseWhat to do
400—Neither pickupTime nor pickupLocation was sent.Send at least one.
400INVALID_REQUESTpickupLocation lacks a description, latitude or longitude.Send all three.
400INVALID_REQUESTYour 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.
400UNKNOWNA 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.
403INSUFFICIENT_PERMISSIONSThe 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.

The error format is described in Errors.

Was this helpful?

Back to your build path: How a journey reaches you →