Create Guest Trip
POSThttps://api.uber.com/v1/guests/trips
¶ Use case
Use this endpoint to create a new trip request.
Scheduled Rides are dispatched before the scheduled pickup_time
such that the driver is expected to arrive at the pickup location at the pickup_time
.
If the request is from a third party (3P) app, please add x-uber-organizationuuid header and the Organization UUID as the value or the request will be denied.
¶ Authorization
OAuth 2.0 Bearer token with the guests.trips
scope.
¶ Ride Types
Ride | Description |
---|---|
Ride on Demand | Request a driver for immediate pickup. |
Scheduled Ride | Automatically send a driver at a specific time in advance. Riders cannot change the pickup time for a scheduled ride without contacting the partner. Only available in certain areas. |
Scheduled Ride - Uber Reserve | Reserve a driver at a specific time in advance. Uber Reserve differs from normal scheduled rides in that a driver will be pre-assigned prior to the trip pickup time. More details can be found in the reserve_info descriptions in the /v1/guests/trips/estimates call. Only available in certain areas. |
Hourly Ride | Reserve a driver at a specific time in advance, for predetermined duration and distance. Hourly Rides are also Reserve Rides, so the rules for “Scheduled Ride - Uber Reserve” also apply. Only available in certain areas. |
Flexible Ride | Set up for riders to redeem on a specific day in advance. A text is sent to provide the rider the ability to request a ride when ready on the specified day. Available everywhere with Uber coverage. |
¶ Request
¶ Example request for a Ride on Demand
Try It
curl -X POST \
-H "authorization: Bearer <access_token>" \
-H 'content-type: application/json' \
-d '{
"guest": {
"email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe",
"phone_number": "+14155550000"
},
"pickup": {
"latitude": 40.752558,
"longitude": -74.006469,
"address": "636 W 28th St New York, NY"
},
"dropoff": {
"latitude": 40.750568,
"longitude": -73.993519,
"address": "Penn Station, New York, NY"
},
"product_id": "b8e5c464-5de2-4539-a35a-986d6e58f186",
"contacts_to_notify" : [
{
"phone_number": "+14155550001",
"contact_event": ["TRIP_BEGAN"]
},
{
"phone_number": "+14155550002",
"contact_event": ["DRIVER_PICKUP_COMPLETED"]
}
]
}' \
'https://api.uber.com/v1/guests/trips/'
¶ Example request for an Hourly Ride
Try It
curl -X POST \
-H "authorization: Bearer <access_token>" \
-H 'content-type: application/json' \
-d '{
"guest": {
"email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe",
"phone_number": "+14155550000"
},
"product_id": "ff4fe398-6cc6-4931-9076-d5bfdde928b6",
"pickup": {
"latitude": 40.752558,
"longitude": -74.006469,
"address": "636 W 28th St New York, NY"
},
"dropoff": {
"latitude": 40.750568,
"longitude": -73.993519,
"address": "Penn Station, New York, NY"
},
"contacts_to_notify" : [
{
"phone_number": "+14155550001",
"contact_event": ["TRIP_BEGAN"]
},
{
"phone_number": "+14155550002",
"contact_event": ["DRIVER_PICKUP_COMPLETED"]
}
]
"hourly": {
"tier": {
"time_in_mins": 120,
"distance": 30,
"distance_unit": "MILE"
}
},
"scheduling": {
"pickup_time": 1698439444000
}
}' \
'https://api.uber.com/v1/guests/trips/'
When using the sandbox environment, the request requires the x-uber-sandbox-runuuid
header with the run_id
as the value (e.g, -H "x-uber-sandbox-runuuid:<run_id>"
).
In order to specify an org for which the ride needs to be billed to, the request requires the x-uber-organizationuuid
header with the Org UUID
as the value (e.g, -H "x-uber-organizationuuid:<org_UUID>"
).
¶ Texting Contacts to Notify
For each SMS, note the following agreement for sharing trip status with trusted contacts:
Please confirm that your company has informed and obtained all necessary rights, permission and legally adequate consent:
- from each rider for Uber to provide detailed trip information, including real-time trip status, to the trusted contacts; and
- from each trusted contact to share the trusted contact’s phone number with Uber and (ii) to receive SMS messages from Uber relating to the ride.
¶ Request body parameters
Field | Type | Description |
---|---|---|
guest |
object | Object containing all the information about the rider. |
guest.first_name |
string | The first name of the rider. |
guest.last_name |
string | The last name of the rider. |
guest.phone_number |
string | Phone number of rider in E.164 (international) format. |
guest.email |
string | Email address of the rider (optional). |
guest.locale |
string | Locale to use when sending text messages to the rider. If not set, defaults to en_US or the locale used for the last create trip request for this guest. |
pickup.latitude |
float | The beginning or “pickup” latitude (required). |
pickup.longitude |
float | The beginning or “pickup” longitude (required). |
pickup.address |
string | The beginning or “pickup” address. |
pickup.place.place_id |
string | The place ID in provider’s namespace. For pickups at specialized pickups, should be set to the ID of an access point; see the /v1/guests/zones API for more detail. |
pickup.place.provider |
string | The name of a provider of location data, e.g. google_places. Should be set to uber_geofences for specialized pickups; see the /v1/guests/zones API for more detail. |
pickup.place.zone_id |
string | (deprecated) For trips at specialized pickups, should be set to the ID of the most immediate parent pickup zone; see the /v1/guests/zones API for more detail. (optional) |
dropoff.latitude |
float | The final or destination latitude (required). |
dropoff.longitude |
float | The final or destination longitude (required). |
dropoff.address |
string | The final or destination address. |
dropoff.place.place_id |
string | The place ID in provider’s namespace. |
dropoff.place.provider |
string | The name of a provider of location data, e.g. google_places. |
start_location.latitude |
float | (deprecated) The beginning or “pickup” latitude. |
start_location.longitude |
float | (deprecated) The beginning or “pickup” longitude. |
start_location.address |
string | (deprecated) The beginning or “pickup” address. |
start_location.place.place_id |
string | (deprecated) The place ID in provider’s namespace. For pickups at specialized pickups, should be set to the ID of an access point; see the /v1/guests/zones API for more detail. |
start_location.place.provider |
string | (deprecated) The name of a provider of location data, e.g. google_places. Should be set to uber_geofences for specialized pickups; see the /v1/guests/zones API for more detail. |
start_location.place.zone_id |
string | (deprecated) For trips at specialized pickups, should be set to the ID of the most immediate parent pickup zone; see the /v1/guests/zones API for more detail. (optional) |
end_location.latitude |
float | (deprecated) The final or destination latitude. |
end_location.longitude |
float | (deprecated) The final or destination longitude. |
end_location.address |
string | (deprecated) The final or destination address. |
end_location.place.place_id |
string | (deprecated) The place ID in provider’s namespace. |
end_location.place.provider |
string | (deprecated) The name of a provider of location data, e.g. google_places. |
product_id |
string | The unique ID of the product being requested. Product IDs for a specific area can be retrieved using the /v1/guests/trips/estimates API. |
fare_id |
string | The unique ID for a fare estimate from the ride request estimate endpoint (required to lock in an upfront fare), or from one of the fare related errors described below (optional). |
expense_memo |
string | A free text field to describe the purpose of the trip for expense reporting (maxlength 64). This value will appear in the trip receipt and any configured expense-reporting integrations like Uber For Business or Business Profiles (optional). |
scheduling.pickup_time |
int | The timestamp (in milliseconds) the request is scheduled for. Required for Scheduled, Reserve and Hourly Rides. If none is provided, the request for a ride will be created immediately. |
scheduling.dropoff_time |
int | The timestamp (in milliseconds) for predicted pickup time based on the dropoff time provided for Uber ReserveSpecific the Estimated Time of Arrival |
deferred_ride_options.pickup_day |
string | Allows the user to request a ride at their convenience on a specific day (YYYY-MM-DD). The ride will be dispatched by the rider after they respond to a text message. Mobile phone numbers only (optional). |
sender_display_name |
string | Name of the sender providing the ride, to be used by Uber in communications with the customer. Please note that names will be truncated at 26 characters. If not set, defaults to the organization name (optional). |
note_for_driver |
string | A free text field for a coordinator to enter a message that will be sent to the driver once the driver gets assigned to a trip (optional). Character limit is 600. |
call_enabled |
boolean | The call_enabled field is a mandatory field. It is set to true by default, and to deactivate phone calls, you must set call_enabled to false. |
contacts_to_notify |
array | List of objects containing information about a third-party contact to text trip link. |
contact_to_notify[].phone_number |
string | Third-party contact phone number to text trip link. |
contact_to_notify[].contact_event |
array | Contact event at which to notify third-party about trip. Acceptable values are TRIP_BEGAN and DRIVER_PICKUP_COMPLETED. |
return_trip_params |
object | Object containing the parameters to create the return trip. |
return_trip_params.start_location |
object | Object containing pickup location details of the return trip. |
return_trip_params.start_location.latitude |
float | The latitude of the pickup location of the return trip. |
return_trip_params.start_location.longitude |
float | The longitude of the pickup location of the return trip. |
return_trip_params.start_location.address |
string | The address of the pickup location of the return trip. |
return_trip_params.start_location.place.place_id |
string | The place ID in provider’s namespace. For pickups at specialized pickups, should be set to the ID of an access point; see the /v1/guests/zones API for more detail. |
return_trip_params.start_location.place.provider |
string | The name of a provider of location data, e.g. google_places. Should be set to uber_geofences for specialized pickups; see the /v1/guests/zones API for more detail. |
return_trip_params.end_location |
object | Object containing dropoff location details of the return trip. |
return_trip_params.end_location.latitude |
float | The latitude of the dropoff location of the return trip. |
return_trip_params.end_location.longitude |
float | The longitude of the dropoff location of the return trip. |
return_trip_params.end_location.address |
string | The address of the dropoff location of the return trip. |
return_trip_params.end_location.place.place_id |
string | The place ID in provider’s namespace. For pickups at specialized pickups, should be set to the ID of an access point; see the /v1/guests/zones API for more detail. |
return_trip_params.end_location.place.provider |
string | The name of a provider of location data, e.g. google_places. Should be set to uber_geofences for specialized pickups; see the /v1/guests/zones API for more detail. |
return_trip_params.scheduling.pickup_time |
int | The timestamp (in milliseconds) in the future the return trip is scheduled for. |
return_trip_params.deferred_ride_options.pickup_day |
string | Allows the rider to request a return ride at their convenience on a specific day (YYYY-MM-DD). The return ride will be dispatched by the rider after they respond to a text message. Mobile phone numbers only. |
return_trip_params.product_id |
string | Unique identifier of a product. Product IDs for a specific area can be retrieved using the /v1/guests/trips/estimates API. |
return_trip_params.fare_id |
string | (Optional) The unique ID for a fare estimate from the ride request estimate endpoint (required to lock in an upfront fare), or from one of the fare related errors described below. |
return_trip_params.note_for_driver |
string | (Optional) A free text field for a coordinator to enter a message that will be sent to the driver once the driver gets assigned to a trip. Please don’t share any sensitive rider info or any Protected Health Information. |
hourly |
object | Object containing booking parameters for Hourly Rides. |
hourly.tier |
object | Object containing the selected hourly tier. |
hourly.tier.time_in_mins |
int | Time to be booked, in minutes. Time and distance must match one of the hourly tier objects, as returned by the /v1/guests/trip/estimates API. |
hourly.tier.distance |
int | Distance to be booked. Time and distance must match one of the hourly tier objects, as returned by the /v1/guests/trip/estimates API. |
hourly.tier.distance_unit |
string | Unit for distance to be booked. Possible values are MILE and KM . Time and distance must match one of the hourly tier objects, as returned by the /v1/guests/trip/estimates API. |
¶ Response
¶ Example response
{
"request_id": "e249c871-7711-4c26-b06c-679cbad6a7c2",
"product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
"status": "processing",
"surge_multiplier": 1,
"guest": {
"guest_id": "b625d1f7-411c-53a8-b2e0-decb81551c2f",
"first_name": "Jane",
"last_name": "Doe",
"phone_number": "+14155550000",
"email": "jane@example.com",
"locale": "en"
}
}
¶ Response body parameters
Field | Type | Description |
---|---|---|
request_id |
string | The unique ID of the trip request. |
product_id |
string | Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles. |
status |
string | The status of the trip request indicating state. |
eta |
int | (deprecated) The estimated time of vehicle arrival in minutes. Null if no drivers available at time of request. |
surge_multiplier |
float | The surge pricing multiplier used to calculate the increased price of a trip request. A multiplier of 1.0 means surge pricing is not in effect. |
guest |
object | Object containing all the information about the rider. |
guest.guest_id |
string | Unique identifier of a rider. |
guest.first_name |
string | The first name of the rider. |
guest.last_name |
string | The last name of the rider. |
guest.phone_number |
string | Phone number of rider in E.164 (international) format. |
guest.email |
string | Email address of the rider. |
guest.locale |
string | The locale that will be used for text messages sent to the rider for this trip. |
linked_request_id |
string | The unique ID of the return trip request. |
estimate_info.pickup_time |
int | The timestamp (in milliseconds) for predicted pickup time based on the dropoff time provided for Uber ReserveSpecific the Estimated Time of Arrival |
estimate_info.eta |
int | The estimated time of vehicle arrival in minutes. Null if no drivers available at time of request. |
pickup |
object | Pickup details are snapped to an Access Point when a trip is created. If the pickup location isn’t snapped, the details will be omitted. |
¶ Pickup object response
The following table provides a detailed breakdown of the pickup
location.
Field | Type | Description |
---|---|---|
pickup.address |
string | The address of the pickup location. |
pickup.is_refined |
boolean | Indicates whether the pickup location is snapped. |
pickup.latitude |
float | The latitude coordinate of the pickup location. |
longitude |
float | The longitude coordinate of the pickup location. |
pickup.timezone |
string | The timezone of the pickup location. |
pickup.title |
string | A brief title or name for the pickup location. |
pickup.subtitle |
string | A subtitle or additional information about the pickup location. |
pickup.status |
string | The current status of the pickup. |
pickup.update_details |
string | Additional details or updates about the pickup. |
pickup.rider_wayfinding_note |
string | Notes to assist the rider in finding the pickup location. |
pickup.place |
object | Contains details about the place. |
pickup.place.place_id |
string | Unique identifier for the place. |
pickup.place.provider |
string | The provider of the place information, e.g., “uber_places”. |
pickup.place.zone_id |
string | An identifier for the zone, if applicable. |
¶ Endpoint errors
A trip request can fail due to higher than normal fares which will require the request to be retried to acknowledge the new fare.
Error metadata fields | Type | Description |
---|---|---|
fare_id |
string | A new unique fare ID that should be used to re-request the ride. This will expire if the time between the estimate and trip request is too long. |
fare_display |
string | The price estimate range and could be null if fare estimates are unavailable. |
multiplier |
float | The surge pricing multiplier used to calculate the increased price of a ride request. A multiplier of 1.0 means surge pricing is not in effect. |
expires_at |
int | Timestamp in seconds. Only non-null if there is a surge multiplier greater than 1. |
Example error 1:
Status-code: 409 Conflict
{
"code": "surge",
"message": "Fare is higher than normal, request again to confirm",
"metadata": {
"fare_id": "dcf8a733-7f11-4544-a9c7-ddea71e46146",
"fare_display": "$12-15",
"multiplier": 1.4,
"expires_at": 1501684062
}
}
Example error 2:
Status-code: 409 Conflict
{
"code": "fare_expired",
"message": "The fare estimate has expired, request again to confirm",
"metadata": {
"fare_id": "dcf8a733-7f11-4544-a9c7-ddea71e46146",
"fare_display": "$9-11",
"multiplier": 1,
"expires_at": 1501684062
}
}
Example error 3:
Status-code: 400 Conflict
{
"message": "You already have a ride scheduled for the selected time!",
"metadata": {
"statusCode": "400"
},
"code": "invalid_pickup_time"
}