Uber Developers

Update Sandbox Run Driver State

POSThttps://sandbox-api.uber.com/v1/guests/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.

¶ Use case

Use this endpoint to change the state of an ephemeral mock driver in the Guest Rides sandbox.

Driver states must be set in the order of a natural trip flow; The drive state can not be changed from ACCEPT to DROPOFF, for example.

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

See the Driver state descriptions for details.

¶ Authorization

OAuth 2.0 Bearer token with the guests.trips scope.

¶ Request

¶ Example request

curl -X POST \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  -d '{
        "run_id": "<run_id>",
        "driver_id": "<driver_id>",
        "driver_state": "ACCEPT"
      }' \
      'https://sandbox-api.uber.com/v1/guests/sandbox/driver-state'

¶ Request body parameters

Field	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`	`object`	The location that the driver should be at when changing states (deprecated).
`driver_location.latitude`	`float`	The latitude of the driver. (deprecated)
`driver_location.longitude`	`float`	The longitude of the driver. (deprecated)
`driver_state`	`string`	The state that the driver should be in. After creating the run, all drivers will be online. See the Driver states table for possible values. (required)

¶ `driver_state` values

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 and will have to be put back to the online state to accept trips.
GO_OFFLINE	Request a driver to go offline. This will mean that the driver will not be offered any trips.

If the driver state is changed to CANCEL after they have been in the ACCEPT state, another driver will be dispatched.

If the driver state is changed to CANCEL after they have been in the ARRIVED state for less than 5 minutes, another driver will be dispatched. Otherwise, another driver will not be dispatched.

¶ Response

¶ Example response

HTTP 200 OK

¶ Endpoint errors

Changing the driver state can fail if the run_id can not be found or if the driver state was not changed within 20 seconds of a trip creation.

If the driver state cannot be changed 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.

If the latter happens, you should create the trip again and try to ACCEPT immediately after creating the trip.

This call can also fail if the driver cannot go into the next state.

{
  "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"
}

Uber

Developers