¶ 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.

After a run is created, all drivers are automatically set to GO_ONLINE state to take any requests.

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 (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. 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"
}