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 to update 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 field is optional on its own, successful assignment requires that at least one is provided.

Note

If you are using the Booking.com Driver App, provide the driverId returned from the create driver endpoint.

Warning

On subsequent calls when providing vehicle details, all previously sent fields must be sent along with any new data. Omitting 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. Must be alphanumeric characters only.	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¶

Creates a driver for a given location and sends an SMS with the Booking.com Taxi Driver App activation link to the driver.

POST /v1/drivers

Request¶

Field	Type	Description	Required
first_name	String	The driver's first name.	Yes
last_name	String	The driver's last name.	Yes
telephone_number	String	The driver's 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 UUID 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¶

Retrieve driver details for your account, with optional filtering by location.

GET /v1/drivers

Request¶

Field	Description	Required
supplier_location_ids	Comma-separated list of location IDs to filter drivers by.	No
size	Number of drivers per page. Default: 100. Minimum: 1.	No
page	Page of drivers to retrieve (zero-indexed).	No

Sample Request¶

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

Response¶

Field	Type	Description
driver_id	String	The UUID representing the driver.
first_name	String	The driver's first name.
last_name	String	The driver's last name.
telephone_number	String	The driver's 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: `PENDING_APP_ACTIVATION` or `APP_ENABLED`

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¶

Retrieve driver details for a specific driver by ID.

GET /v1/drivers/:driver_id

Request¶

Field	Description	Required
driver_id	The UUID of the driver (path parameter).	Yes

Sample Request¶

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

Response¶

Field	Type	Description
driver_id	String	The UUID representing the driver.
first_name	String	The driver's first name.
last_name	String	The driver's last name.
telephone_number	String	The driver's 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: `PENDING_APP_ACTIVATION` or `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¶

Update driver details for a given driver by ID.

PUT /v1/drivers/:driver_id

Request¶

Note

All fields are optional. Only include the fields you wish to update — omitted fields remain unchanged.

Field	Type	Description	Required
first_name	String	The driver's first name.	No
last_name	String	The driver's last name.	No
supplier_location_ids	Array	The IDs of the location the driver operates within.	No

Sample Request¶

{
    "first_name": "Nick",
    "last_name": "Samson",
    "supplier_location_ids": ["12"]
}

Response¶

Field	Type	Description
driver_id	String	The UUID representing the driver.
first_name	String	The driver's first name.
last_name	String	The driver's last name.
telephone_number	String	The driver's 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: `PENDING_APP_ACTIVATION` or `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¶

Delete a driver by ID.

DELETE /v1/drivers/:driver_id

Sample Request¶

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

Response¶

HTTP 200 - OK¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

HTTP 404 - Not Found¶

Resend activation link¶

Resend the Booking.com Taxi Driver App activation SMS to a driver.

POST /v1/drivers/:driver_id/activation

Sample Request¶

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

References¶

Assign a driver¶

Request¶

Sample Request¶

Response¶

HTTP 204 - No Content¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 404 - Not Found¶

Create a driver¶

Request¶

Sample Request¶

Response¶

HTTP 201 - Created¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

Retrieve all drivers¶

Request¶

Sample Request¶

Response¶

HTTP 200 - OK¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

Retrieve a single driver¶

Request¶

Sample Request¶

Response¶

HTTP 200 - OK¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

HTTP 404 - Not Found¶

Update a driver¶

Request¶

Sample Request¶

Response¶

HTTP 200 - OK¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

HTTP 404 - Not Found¶

Delete a driver¶

Sample Request¶

Response¶

HTTP 200 - OK¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

HTTP 404 - Not Found¶

Resend activation link¶

Sample Request¶

Response¶

HTTP 200 - OK¶

HTTP 400 - Bad Request¶

HTTP 401 - Unauthorized¶

HTTP 403 - Forbidden¶

HTTP 404 - Not Found¶

Further reading¶