Assign a driver and a vehicle
Assign, change or remove the driver and vehicle of a journey.
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.
/journeys/488213/assign-driverReferencecurl --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}'HTTP/1.1 204 No ContentThe 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.
/journeys/488213/assign-vehicleReferencecurl --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}'HTTP/1.1 204 No ContentGet a journey now shows both:
{ "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.
/journeys/488213/assign-driverReferencecurl --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}'HTTP/1.1 204 No ContentWithout 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:
/journeys/488213/unassign-driverReferencecurl --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'HTTP/1.1 204 No ContentTo remove only the vehicle, for example before you assign another car to the same driver:
/journeys/488213/unassign-vehicleReferencecurl --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'HTTP/1.1 204 No ContentRemoving 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
| 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 | Another driver is assigned and reassign is false. | Send reassign: true, or unassign first. |
400 | DRIVER_NOT_ASSIGNED | You assigned a vehicle before a driver. | Assign the driver first. |
400 | 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. |
The error format is described in Errors.