Uber Developers

Update Sandbox Run Driver State

POSThttps://sandbox-api.uber.com/v1/health/sandbox/driver-state

Privileged and Confidential This endpoint design has been confidentially shared with you. It is still under development and is subject to change without notice. Please do not share this document or API endpoint details with anyone who is not authorized to have access. For more information read about scopes.

Changes the driver state during a run. See Sandbox Guide for details on how to use interactive sandbox trips.

¶ Authorization

OAuth 2.0 Bearer token with the health scope.

¶ Driver States

The driver states must be done in order. The driver will need to ACCEPT the ride, then have ARRIVED at the pickup location. The driver will need to BEGIN_TRIP before the driver can DROPOFF the rider.

Driver State	Description
ACCEPT	Request a driver to accept the offer. The driver needs to be near the pickup location and needs to be offered the trip. It is recommended to ACCEPT the trip within 15 seconds of creating a trip. Not supported for Uber Reserve and Hourly Rides.
ARRIVED	Request a driver to arrive to pickup location.
BEGIN_TRIP	Request a driver to begin the trip.
DROPOFF	Request a driver to arrive to dropoff location.
CANCEL	Request a driver to cancel the trip after they have changed state to ACCEPT or ARRIVED.
GO_ONLINE	Request a driver to go online. On run creation, the driver is automatically put in this state. After 5 minutes, the driver may automatically GO_OFFLINE.
GO_OFFLINE	Request a driver to go offline. This will mean that the driver will not be offered any trips.

If you want to change the Driver’s location in between trips, you can use GO_OFFLINE and then GO_ONLINE with the new driver_location.

¶ Example Request

Try It Replace the token in the below request to use it a terminal to change a driver’s state. Note the runID and driverID will need to change.

curl -X POST \
  -H 'authorization: Bearer REPLACETOKEN' \
  -H 'content-type: application/json' \
  -d '{
        "run_id": "4c11a40a-950a-4486-baf4-59858300190b",
        "driver_id": "actor_driver0",
        "driver_state": "ACCEPT"
  }' \
  'https://sandbox-api.uber.com/v1/health/sandbox/driver-state'

Name	Type	Description
`run_id`	`string`	A unique identifier of a sandbox create run request (required)
`driver_id`	`string`	The driver ID to use to change the driver’s state (required)
`driver_location`	`array`	The location that the driver should be at when changing states (optional).
`driver_location.latitude`	`float`	The latitude of the driver
`driver_location.longitude`	`float`	The longitude of the driver
`driver_state`	`string`	The state that the driver should be in. After creating the run, all drivers will be online. The options are: ACCEPT, ARRIVED, BEGIN_TRIP, DROPOFF, CANCEL, GO_ONLINE, GO_OFFLINE (required)

¶ Errors

A change driver state request can fail if the RunID is not found or if the driver was not given an offer during the 20 second period. Make sure you run this soon after requesting a trip. If the driver was unable to ACCEPT after creating a trip, it is likely that the driver is too far from the pickup location or that you waited too long to ACCEPT after creating the trip. This can also fail if the driver cannot go into the next state. After a run is created, all drivers are automatically online to take any requests.

{
  "code": "entity_not_found",
  "message": "RunID is not valid"
}

{
  "code": "entity_not_found",
  "message": "The driver was unable to accept. Try again or set driver location closer to pickup"
}

{
  "code": "invalid_request_parameters",
  "message": "The driver was unable to change to this state. Try a different state"
}