¶ 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. Note: Flexible trips now have an extended expiration time until 6A.M the next morning.

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

1. from each rider for Uber to provide detailed trip information, including real-time trip status, to the trusted contacts; and
2. 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. guests
policy_uuid	string	ID of object that contains permission and product type.
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. Please use pickup.latitude
start_location.longitude	float	(deprecated) The beginning or pickup longitude. Please use pickup.longitude
start_location.address	string	(deprecated) The beginning or pickup address. Please use 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. Please use pickup.place.place_id
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. Please use pickup.place.provider
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). Please use pickup.place.zone_id
end_location.latitude	float	(deprecated) The final or destination latitude. Please use dropoff.latitude
end_location.longitude	float	(deprecated) The final or destination longitude. Please use dropoff.longitude
end_location.address	string	(deprecated) The final or destination address.Please use dropoff.address
end_location.place.place_id	string	(deprecated) The place ID in provider’s namespace. Please use dropoff.place.place_id
end_location.place.provider	string	(deprecated) The name of a provider of location data, e.g. google_places. Please use dropoff.place.provider
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.amount	double	The price of this hourly tier.
hourly.tier.formatted_time_and_distance_package	string	Human-readable hourly tier time and distance information, such as "2 hrs/30 miles"
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.
additional_guests	array	Array of additional guests (guests) of the trip. Does not include the host rider. (Supported for all ride types except Hourly)
stops	array	An array of objects containing the location of the trip’s intermediate stops. Does not include pickup and dropoff. (Supported for all ride types)

¶ Guest object parameters Back to top

Name	Type	Description
guest.guest_id	string	(Optional) Unique identifier of a rider.
guest.first_name	string	(Required if guest.guest_id is omitted) Rider’s first name.
guest.last_name	string	(Required if guest.guest_id is omitted) Rider’s last name.
guest.email	string	(Optional) Rider’s email address.
guest.phone_number	string	(Required if guest.guest_id is omitted) Phone number of a rider in E.164 (international) format.
guest.locale	string	(Optional) The locale the rider was created in. Defaults to en.

¶ Stops object parameters Back to top

Name	Type	Description
stops.latitude	float	(Required) The latitude of the intermediate stop.
stops.longitude	float	(Required) The longitude of the intermediate stop.
stops.address	string	(Optional) The intermediate stop complete address.
stops.place.place_id	string	(Optional) The place id in provider’s namespace.
stops.place.provider	string	(Optional) The name of a provider of a location data.
stops.place.zone_id	string	(Optional) For trips at specialized pickups, the ID of the most immediate parent pickup zone.
stops.timezone	string	(Optional) The timezone at intermediate stop.
stops.title	string	(Optional) The intermediate stop street address.

¶ 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.
pickup.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"
}

¶ Endpoint Possible Errors

HTTP Status	Code	Description
400	validation_failed	This error occurs when required fields are missing or invalid in the request payload. For example, if the product_id or guest.phone_number field is missing in the request payload.
400	fare_expired	This error occurs when you attempt to create a trip using an expired fare_id. Ensure the trip is created before the expires_at time provided in the trip estimates response.
400	validation_failed	Your request could not be processed. This rider’s number is associated with a teen account. Only the parent or guardian linked to the teen’s account can book rides for them.
401	unauthorized	Authorization failed. The client lacks valid auth credentials for the requested resource.
403	forbidden	The client does not have permission to access the requested resource.
404	not_found	The requested resource or entity could not be found on the server.
500	internal_server_error	An unexpected error occurred on the server while processing the request.