Getting Started with the Uber Direct APIs
This guide walks through retrieving your Uber Direct developer credentials, using them to get an OAuth token, and making DaaS API calls using curl.
We will also take a look at the Direct Dashboard, a web interface for creating and managing deliveries.
To follow this guide, you will need access to the Direct Dashboard. Please work with your Uber Account Manager to get set up.
¶ Retrieve developer credentials
-
After working with your Uber Account Manager, you should receive an invitation via email to access the Direct Dashboard. Follow the instructions in the email to log into the Direct Dashboard, and click on the Developer tab in the bottom-left.
-
Retrieve your Client ID, Client Secret, and Customer ID from the section shown below:
The Client ID and Client secret will be used to generate an OAuth token. The Customer ID is a GUID that will be used in the URLs of your API calls.
Note that Test mode in the top-right is toggled On. This indicates that these credentials are for your test sandbox environment, and real-world deliveries will not be created when you call the APIs. Once your account is approved for Production deliveries, the switch will be enabled, and will allow you to toggle between viewing your Test and Production credentials.
¶ Get an OAuth token using curl
curl --request POST 'https://login.uber.com/oauth/v2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=XYZABC-12XXXXXXXXXXXXXXX' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=eats.deliveries'
Sample response:
{
"access_token": "<TOKEN>",
"expires_in": 2592000,
"token_type": "Bearer",
"scope": "eats.deliveries"
}
¶ Make a DaaS API call using curl
Next, call the Create Quote endpoint, which takes in a pair of addresses and returns a time estimate and fee quote for delivery. The token from the last step is included in the Authorization header.
curl -X POST 'https://api.uber.com/v1/customers/<CUSTOMER_ID>/delivery_quotes' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"pickup_address": "20 W 34th St, New York, NY 10001",
"dropoff_address": "285 Fulton St, New York, NY 10007"
}'
If successful, you will receive a JSON response like the one below, indicating a delivery fee of $5.32, a pickup ETA of 14 minutes, and a total end-to-end dropoff time of 32 minutes.
{
"kind": "delivery_quote",
"id": "dqt_AoJ7-T_ASESIMBIVSc_xzx",
"created": "2022-06-22T01:41:01.607Z",
"expires": "2022-06-22T01:56:01.607Z",
"fee": 532,
"currency": "usd",
"currency_type": "USD",
"dropoff_eta": "2022-06-22T02:13:56Z",
"duration": 32,
"pickup_duration": 14
}
For more examples, see the Authentication guide.
¶ Create test deliveries
You can create a delivery on Uber Direct using either the Direct Dashboard or the APIs.
Using the Dashboard:
Clicking the + New Delivery button in the top-left shows the Create Order page:
After the order is created:
Creating a delivery using the DaaS API via curl:
curl -X POST 'https://api.uber.com/v1/customers/<CUSTOMER_ID>/deliveries' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
"pickup_address": "20 W 34th St, New York, NY 10001",
"pickup_name": "My Store",
"pickup_phone_number": "4444444444",
"dropoff_address": "285 Fulton St, New York, NY 10007",
"dropoff_name": "Reese Ippient",
"dropoff_phone_number": "5555555555",
"pickup_latitude": "40.748718",
"pickup_longitude": "-73.985352",
"dropoff_latitude": "40.712940",
"dropoff_longitude": "-74.013450",
"manifest_items": [
{
"name": "Cell phone box",
"quantity": 1,
"size": "small"
}
],
external_store_id: "mystore02"
}'
API Response:
{
"id": "del_Pw2e2GpnS0Gf0XUjb2xi3R",
"quote_id": "dqt_Pw3f2GpnS0Gf0WUjb2yj3Q",
"status": "pending",
"complete": false,
"kind": "delivery",
"pickup": {
"name": "My Store",
"phone_number": "4444444444",
"address": "20 W 34th St, New York, NY 10001",
"detailed_address": {
"street_address_1": "20 W 34th St",
"street_address_2": "",
"city": "New York",
"state": "NY",
"zip_code": "10118",
"country": "US"
},
"notes": "",
"location": {
"lat": 40.74838,
"lng": -73.98477
}
},
"dropoff": {
"name": "Reese Ippient",
"phone_number": "+15555555555",
"address": "285 Fulton St, New York, NY 10007",
"detailed_address": {
"street_address_1": "One World Trade Center",
"street_address_2": "",
"city": "New York",
"state": "NY",
"zip_code": "10006",
"country": "US"
},
"notes": "",
"location": {
"lat": 40.71301,
"lng": -74.01317
}
},
"manifest": {
"description": "1 X Cell phone box\n",
"total_value": 0
},
"manifest_items": [
{
"name": "Cell phone box",
"quantity": 1,
"size": "small",
"must_be_upright": false
}
],
"created": "2022-06-22T02:33:14.691Z",
"updated": "1970-01-01T00:00:00Z",
"pickup_ready": "2022-06-22T02:33:14Z",
"pickup_deadline": "2022-06-22T02:53:14Z",
"dropoff_ready": "2022-06-22T02:33:14Z",
"dropoff_deadline": "2022-06-22T03:47:43Z",
"pickup_eta": "2022-06-22T02:47:34Z",
"dropoff_eta": "2022-06-22T03:15:57Z",
"related_deliveries": null,
"fee": 532,
"currency": "usd",
"tracking_url": "https://www.ubereats.com/orders/xxxxxxxx-6a67-4b41-9fd1-65236f6c62dd",
"undeliverable_action": "",
"courier_imminent": false,
"courier": null,
"live_mode": false,
"undeliverable_reason": "",
"uuid": "3AFXXXXXXXX4B419FD165236F6C62DD",
"fences": null,
"external_id": "",
"items_acquired": null,
"state_changes": null
}
Descriptions for all of the fields in the request and response can be found in the Create Delivery documentation.
We can view a list of the deliveries we’ve created by making a GET request to the same endpoint:
curl 'https://api.uber.com/v1/customers/<CUSTOMER_ID>/deliveries' \
-H 'Authorization: Bearer <TOKEN>'
Response:
{
"total_count": 2,
"data": [
{
"id": "del_Pw2e2GpnS0Gf0XUjb2xi3R",
"quote_id": "dqt_Pw3f2GpnS0Gf0WUjb2yj3Q",
"status": "pending",
"complete": false,
"kind": "delivery"
// . . .
},
{
"id": "del_nk5F121oQCafa_6p36empA",
"quote_id": "dqt_mk4F121oPCafa_6p337empB",
"status": "pending",
"complete": false,
"kind": "delivery"
// . . .
}
],
"next_href": "api.postmates.com/v1/customers/3b0c0038-2d5d-45a6-951e-1ecf9e3eb331/deliveries?offset=2"
}
We can also see both created deliveries show up in the Dashboard:
Note: We provided the address string 285 Fulton St, and after geocoding, the address was resolved to One World Trade Center.
¶ Simulating Deliveries
To test a delivery we have created, we need to simulate the Courier picking up the orders and delivering them to the customer.
We can carry out these steps automatically using the Robo Courier. The Robo Courier automatically picks up our order and mocks its location to deliver it to the customer.
The delivery request below includes the test_specifications object which activates the Robo Courier for this order. Full details are in the Robo Courier guide
curl -X POST 'https://api.uber.com/v1/customers/<CUSTOMER_ID>/deliveries' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"pickup_address": "20 W 34th St, New York, NY 10001",
"pickup_name": "My Store",
"pickup_phone_number": "4444444444",
"dropoff_address": "285 Fulton St, New York, NY 10007",
"dropoff_name": "Reese Ippient",
"dropoff_phone_number": "5555555555",
"manifest_items": [
{
"name": "Cell phone box",
"quantity": 1,
"size": "small"
}
],
"test_specifications": {
"robo_courier_specification": {
"mode": "auto"
}
}
}'
After you make this request, you can monitor the delivery as it advances through each state (via the Dashboard or the tracking_url found in the Create Delivery response):
The Robo Courier arrives:
~30 seconds later:
~30 seconds later:
¶ Next Steps
Now you can use the Direct Dashboard, make API calls, and create, monitor, and simulate deliveries. Next, dive deeper into the DaaS platform:
- See the DaaS API Reference to try the remaining endpoints & fields.
- Walk through the Testing Guide to log in as a Courier and manually simulate a delivery
- Learn more about using the Robo Courier