Skip to content

Assign a driver and a vehicle

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

Updated · 3 min read

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).

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.

PUT/journeys/488213/assign-driverReference
Sign in to fill in your staging key. Sign in
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}'
Response 204
HTTP/1.1 204 No Content

The journey moves from CONFIRMED to PLANNED, and you receive journeyStatusChangedEvent. 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.

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.

PUT/journeys/488213/assign-vehicleReference
Sign in to fill in your staging key. Sign in
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}'
Response 204
HTTP/1.1 204 No Content

Get a 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.

PUT/journeys/488213/assign-driverReference
Sign in to fill in your staging key. Sign in
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}'
Response 204
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:

PUT/journeys/488213/unassign-driverReference
Sign in to fill in your staging key. Sign in
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'
Response 204
HTTP/1.1 204 No Content

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

PUT/journeys/488213/unassign-vehicleReference
Sign in to fill in your staging key. Sign in
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'
Response 204
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 events.

Errors

StatusCodeCauseWhat to do
400—name or phoneNumber is missing, or the phone number is not in international format.Send + and digits only, such as +447700900456.
400JOURNEY_ALREADY_ASSIGNED_TO_OTHER_DRIVERAnother driver is assigned and reassign is false.Send reassign: true, or unassign first.
400DRIVER_NOT_ASSIGNEDYou assigned a vehicle before a driver.Assign the driver first.
400VEHICLE_ALREADY_ASSIGNEDA vehicle is assigned and reassign is false.Send reassign: true, or unassign the vehicle first.
400UNKNOWNThe journey is completed or cancelled ("already in a final state").Do not change finished journeys.
403INSUFFICIENT_PERMISSIONSThe 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.

The error format is described in Errors.

Was this helpful?