¶ Guest Rides Sandbox Overview

The Guest Rides Sandbox API provides development endpoints for testing the functionality of an application without making calls to the production Uber platform.

To use the Sandbox, make calls to https://sandbox-api.uber.com.

Environment	URL
Production	https://api.uber.com
Sandbox	https://sandbox-api.uber.com

All requests made to the Sandbox environment are ephemeral.

Please contact support to be whitelisted if you get an “Unauthorized” response when calling the Sandbox API.

The Sandbox environment relies on the concept of “runs” to create interactive test trips and mock driver behavior. A run will create temporary riders and drivers that will disappear after 8 hours.

Look for Try It tags throughout the documentation for sandbox examples.

¶ Available Endpoints

Method	Endpoint	Description
POST	/v1/guests/sandbox/run	Creates a new run to setup interactive sandbox trips.
GET	v1/guests/sandbox/run/:run_id	Retrieves the run’s test driver_ids to use in /v1/guests/sandbox/driver-state.
POST	/v1/guests/sandbox/driver-state	Changes the driver state during a run.

¶ Mocking trips

Because mocking a trip requires the use of “Sandbox runs”, it may be difficult to mock a trip using your application code.

Often an independent script or test app is easier to use.

One of the best tools to use is Postman. Uber has a Guest Rides Postman API collection to help you get started. Follow the “Importing and exporting data” guide from Postman to import the collection. Make sure to update the placeholders with your real values, such as <client_id>, <client_secret>, and <request_id>.

This animated gif provides an example of a mock trip being executed using Postman.

¶ Getting started

¶ 1. Create a run

First, call /v1/guests/sandbox/run to create a run.

This will setup test riders and drivers that will temporarily exist for 8 hours.

The run_id will be re-usable as long as you want to make test trips in the same city for the duration of the run.

Ensure that the pickup_location and dropoff_location are in a city that Uber operates in. This can be verified using /v1/guests/trips/estimates.

Driver latitude and longitude are optional fields; if they are empty, the driver will be placed randomly near the pickup location.

Each {} in the driver_locations array is required to show that a driver needs to be created. Example:

curl -X POST \
  -H 'authorization: Bearer REPLACETOKEN' \
  -H 'content-type: application/json' \
  -d '{
      "driver_locations": [{}],
      "pickup_location": {
        "latitude": 40.7517665,
        "longitude": -73.98786252
      },
      "dropoff_location": {
        "latitude": 40.75279,
        "longitude": -74.00465
      },
      "parent_product_type_id": "b8e5c464-5de2-4539-a35a-986d6e58f186"
  }' \
  'https://sandbox-api.uber.com/v1/guests/sandbox/run'

When this call is made, it may take up to a minute for the mock setup to complete.

¶ 1a. Auto accept trip

Optionally, you can set preferences during run creation. If auto_accept_trip preference is set, trip will be automatically accepted within a minute after creation. In this case, there’s no need to call /v1/guests/sandbox/driver-state with ACCEPT state. Instead you can wait for trip status webhook for ACCEPTED status, and then proceed with manual simulation for rest of the driver states. Note that Driver state simulation for other states such as BEGIN_TRIP, DROPOFF, CANCEL is still required to be performed manually. Currently only supported for on-demand trips.

NOTE: If using Auto Accept Trip feature, make sure to create a trip within 5 minutes of run creation. Otherwise, the preference will be reset. Also the preference is only valid for one trip per run. If you want to test more than 1 trips with a single run, use manual /v1/guest-rides/sandbox/driver-state API with ACCEPT state for simulation instead of using preference.

curl -X POST \
  -H 'authorization: Bearer REPLACETOKEN' \
  -H 'content-type: application/json' \
  -d '{
      "driver_locations": [{}],
      "pickup_location": {
        "latitude": 40.7517665,
        "longitude": -73.98786252
      },
      "dropoff_location": {
        "latitude": 40.75279,
        "longitude": -74.00465
      },
      "parent_product_type_id": "b8e5c464-5de2-4539-a35a-986d6e58f186",
      "preferences" : {
        "auto_accept_trip": true
      }
  }' \
  'https://sandbox-api.uber.com/v1/guests/sandbox/run'

¶ 2. Obtain the run_id

The POST /run call will return a run_id, which will then be needed in the header in subsequent calls. (e.g, -H "x-uber-sandbox-runuuid:4c11a40a-950a-4486-baf4-59858300190b")

The following endpoints will accept this header:

• /v1/guests/trips/estimates if you plan on using up front pricing (fare_id)
• POST /v1/guests/trips

¶ 3. Obtain the test driver_ids

After waiting one minute, call v1/guests/sandbox/run/:run_id.

This will return the test driver_ids that you will need for /v1/guests/sandbox/driver-state.

If the GET /run call failed, it means that the inputs for POST /run were probably invalid.

The driver is automatically changed to a GO_ONLINE state but will GO_OFFLINE after 5 minutes if there is no driver activity.

¶ 4. Obtain the product_id

You will need to query /v1/guests/trips/estimates to get a product_id that corresponds to the parent_product_type_id you chose in /v1/guests/sandbox/run.

Make sure that the product_id does NOT have "no_cars_available": true.

If the product_id shows "no_cars_available": true, then drivers may have gone offline, and you will need to use /v1/guests/sandbox/driver-state to change the driver’s state to GO_ONLINE.

If you want to create a trip with upfront fare enforced, you can also use the fareID in the /v1/guests/trips/estimates response to then pass into POST /v1/guests/trips.

¶ 5. Create a trip request

Call POST /v1/guests/trips to create a trip request.

¶ 6. Change the driver state

Call /v1/guests/sandbox/driver-state to change the driver’s state.

In order to complete a trip, the states to call are (ACCEPT, ARRIVED, BEGIN_TRIP, DROPOFF).

The driver can CANCEL after the ACCEPT or ARRIVED state.

¶ 7. Fetch trip details

Call GET /v1/guests/trips/{trip_id} to fetch details of the trip any time after creation.

¶ 8. Fetch trip receipt

Receipts for test trips are generally available a minute after the trip is complete. Call GET /v1/guests/trips/{trip_id}/receipt to fetch the receipt for a trip that you just created.

Note: The receipt webhooks are not available in Sandbox environment at the moment.

¶ Multiple trips

To make multiple subsequent trips in the same city, you can re-use the run_id.

If you want to change the driver’s location between trips, you have to change the driver’s state to GO_OFFLINE and then change the driver’s state to GO_ONLINE with driver_location.

The driver_location should be near the new pickup location in order for the driver to ACCEPT the next trip request.

Then you can request a trip and complete the trip by changing the driver’s state using the same steps as above.

¶ Scheduled Trips

If you are making a scheduled trip, the driver may GO_OFFLINE before the trip is dispatched.

Set the driver state to GO_ONLINE near the pickup location within a minute of the scheduled pickup time.

¶ Flexible Trips

Flexible trips follow a different flow because no dispatchable trip exists until the offer is redeemed. The complete Sandbox flow is:

1. Create the trip with deferred_ride_options.pickup_day set. The trip reads as scheduled until the offer window opens (00:00 local time on pickup_day), then as offered — both statuses refer to the same unredeemed offer.
2. Set the driver state to GO_ONLINE before redeeming the offer.
3. Redeem the offer using one of the following:
   • Call POST /v1/guests/trips/{request_id}/dispatch directly. This is the recommended approach for Sandbox testing as it does not require the passenger to reply to an SMS. It works against Sandbox runs the same way as in production.
   • Alternatively, wait for the passenger to redeem via the SMS sent to them.
   • Note: the dispatch call only succeeds once the offer window has opened (on pickup_day). Calling it before the window opens returns Ride cannot be dispatched until pickup day. Calling it after the offer has already been redeemed or expired returns This ride can no longer be dispatched.
4. Calling /v1/guests/sandbox/driver-state with ACCEPT before the offer has been redeemed will fail. This is expected — no trip exists yet to accept.
5. Once redeemed, proceed with the standard driver states: ACCEPT, ARRIVED, BEGIN_TRIP, DROPOFF.

You can also update the trip (including pickup location) at any point while it is scheduled or offered using PUT /v1/guests/trips/{trip_id}. See the update-eligibility table for the full field list.

¶ Uber Reserve and Hourly Trips

The Sandbox environment doesn’t provide full support for simulating Uber Reserve and Hourly Rides.

It is not possible to set the driver state to ACCEPT, and this prevents updating the destination and intermediate stops for these trips using the PUT /v1/guests/trips/{trip_id} API.