References¶

Assign a driver¶

The V2 assign driver endpoint allows a driver and/or vehicle to be assigned to a booking.

Note

Driver and vehicle can be assigned separately or together, and the endpoint can be called multiple times for the same booking, in order to update the driver/vehicle details.

Booking must be in either the ACCEPTED or DRIVER_ASSIGNED state

POST /v2/bookings/:bookingReference/assignDriver

Request¶

To assign a driver to a booking, you must provide at least one of the following fields: driverId, driver, or vehicle. While each of these fields is optional on its own, successful assignment requires that at least one field is provided.

Note

If you are using Driver App, please provide the driver ID

Warning

On subsequent calls when providing vehicle details, all previously sent fields must be sent along with any new data.
Omitting these fields will cause the previous data to be overwritten with null.

Field	Type	Description	Required
driverId	String	Driver's Id. Limited to 255 characters.	No
driver.firstName	String	Driver's first name. Limited to 255 characters.	Yes - but only when driver details are being provided
driver.lastName	String	Driver's last name. Limited to 255 characters.	Yes - but only when driver details are being provided
driver.telephoneNumber	String	Driver's telephone number. Limited to 255 characters.	Yes - but only when driver details are being provided
driver.photoURL	String	A URL for the driver's photo. Limited to 2000 characters.	No
vehicle.make	String	Vehicle brand. Limited to 50 characters.	No
vehicle.model	String	Vehicle model. Limited to 50 characters.	No
vehicle.registration	String	Vehicle registration. Limited to 50 characters.	No
vehicle.colour	String	Vehicle colour. Limited to 50 characters.	No
stateHash	String	The latest state hash for the booking.	Yes

Sample Request¶

{
    "driverId": "df24b1354b6e96fd738f7ccdfcf01d8be35064666a82934ff5c58feefbcfcb7f",
    "driver": {
        "firstName": "Nick",
        "lastName": "Samson",
        "telephoneNumber": "+911234567898",
        "photoURL": "https://example.com/driver.jpg"
    },
    "vehicle": {
        "make": "Tesla",
        "model": "Model S",
        "registration": "B00K 1NG",
        "colour": "Black"
    },
    "stateHash": "4b2c68f6c847284e73c73b26693d9905"
}

Response¶

Http 204 - No Content¶

Http 400 - Bad Request¶

Example 400 response:

{
    "errorCode": "9e753833-36db-4922-9167-e5fed5f0cb7d",
    "errorMessage": "stateHash: field is required"
}

Http 401 - Unauthorized¶

Http 404 - Not Found¶

Example 404 response:

{
    "errorCode": "9e753833-36db-4922-9167-e5fed5f0cb7d",
    "errorMessage": "Booking not found for bookingReference: xxx"
}

Create a driver¶

The create driver endpoint allows to create a driver for a given location and sends an SMS with the link to activate the Booking.com Taxi Driver App to the driver.

POST /v1/drivers

Request¶

Field	Type	Description	Required
first_name	String	The drivers first name.	Yes
last_name	String	The drivers last name.	Yes
telephone_number	String	The drivers phone number in E.164 format.	Yes
supplier_location_ids	Array	The IDs of the location the driver operates within.	Yes

Sample Request¶

Note

You can retrieve supplier location IDs from the locations endpoint.

{
    "first_name": "Example",
    "last_name": "Driver",
    "telephone_number": "+441632960881",
    "supplier_location_ids": ["12", "15", "20"]
}

Response¶

Field	Type	Description
driver_id	String	The ID representing the newly created driver.

HTTP 201 - Created¶

{
  "driver_id": "94cddcce-0a92-4ced-ad5c-67reretff0ff"
}

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

Retrieve all drivers¶

This endpoint is used to retrieve driver details, it can also filter the driver list to a specific location.

GET /v1/drivers

Request¶

Field	Description	Required
supplier_location_ids	The IDs of the location the driver operates within.	No
size	Retrieve the specified number of bookings per page, we will return 500 bookings per page by default.	No
page	Page of bookings to retrieve.	No

Sample Request¶

GET /v1/drivers?supplier_location_ids=12,15,20&size=50&page=1

Response¶

HTTP 200 - OK¶

{
    "links": [
        {
            "rel": "next",
            "href": "/v1/drivers?supplier_location_ids=124,80&size=2&page=1",
            "type": "GET"
        }
    ],
    "drivers": [
        {
            "driver_id": "94cddcce-0a92-4ced-ad5c-67reretff0ff",
            "first_name": "Nick",
            "last_name": "Samson",
            "telephone_number": "+911234567898",
            "supplier_location_ids": ["12"],
            "status": "PENDING_APP_ACTIVATION"
        }
    ]
}

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

Retrieve a single driver¶

Allows you to retrieve the driver details for a given driver, by ID.

GET /v1/drivers/:driver_id

Request¶

Field	Description	Required
driver_id	The ID of the driver.	Yes

Sample Request¶

GET /v1/drivers/94cddcce-0a92-4ced-ad5c-67reretff0ff

Response¶

Field	Type	Description
driver_id	String	The ID representing the driver.
first_name	String	The drivers first name.
last_name	String	The drivers last name.
telephone_number	String	The drivers phone number in E.164 format.
supplier_location_ids	Array	The IDs of the location the driver operates within.
status	String	The current app status of the driver, can be one of: `PENDING_APP_ACTIVATION` `APP_ENABLED`

HTTP 200 - OK¶

{
    "driver_id": "94cddcce-0a92-4ced-ad5c-67reretff0ff",
    "first_name": "Nick",
    "last_name": "Samson",
    "telephone_number": "+911234567898",
    "supplier_location_ids": ["12"],
    "status": "PENDING_APP_ACTIVATION"
}

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

HTTP 404 - Not Found¶

Update a driver¶

Allows you to update the driver details for a given driver, by ID.

PUT /v1/drivers/:driver_id

Request¶

Field	Type	Description	Required
driver_id	String	The ID representing the driver.	Yes
first_name	String	The drivers first name.	Yes
last_name	String	The drivers last name.	Yes
supplier_location_ids	Array	The IDs of the location the driver operates within.	Yes

Sample Request¶

{
    "driver_id": "94cddcce-0a92-4ced-ad5c-67reretff0ff",
    "first_name": "Nick",
    "last_name": "Samson",
    "supplier_location_ids": ["12"]
}

Response¶

Field	Type	Description
driver_id	String	The ID representing the driver.
first_name	String	The drivers first name.
last_name	String	The drivers last name.
telephone_number	String	The drivers phone number in E.164 format.
supplier_location_ids	Array	The IDs of the location the driver operates within.
status	String	The current app status of the driver, can be one of: `PENDING_APP_ACTIVATION` `APP_ENABLED`

HTTP 200 - OK¶

{
    "driver_id": "94cddcce-0a92-4ced-ad5c-67reretff0ff",
    "first_name": "Nick",
    "last_name": "Samson",
    "telephone_number": "+911234567898",
    "supplier_location_ids": ["12"],
    "status": "PENDING_APP_ACTIVATION"
}

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

HTTP 404 - Not Found¶

Delete a driver¶

Allows you to delete a driver by ID.

DELETE /v1/drivers/:driver_id

Request¶

Field	Type	Description	Required
driver_id	String	The ID representing the driver.	Yes

Sample Request¶

{
  "driver_id": "94cddcce-0a92-4ced-ad5c-67reretff0ff"
}

Response¶

HTTP 200 - OK¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

HTTP 404 - Not Found¶

Activate a driver¶

This endpoint can be used to resend a Booking.com Taxi Driver App activation link.

POST /v1/drivers/:driver_id/activation

Request¶

Field	Type	Description	Required
driver_id	String	The ID representing the driver.	Yes

Sample Request¶

{
  "driver_id": "94cddcce-0a92-4ced-ad5c-67reretff0ff"
}