Three lines

Uber

Developers

Create Guest Trip

POSThttps://api.uber.com/v1/guests/trips

Privileged and Confidential This endpoint design has been confidentially shared with you. It is still under development and is subject to change without notice. Please do not share this document or API endpoint details with anyone who is not authorized to have access. For more information read about scopes.

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

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"
        },
        "start_latitude": 40.752558,
        "start_longitude": -74.006469,
        "start_address": "636 W 28th St New York, NY",
        "end_latitude": 40.750568,
        "end_longitude": -73.993519,
        "end_address": "Penn Station, New York, NY",
        "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/'

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.
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.
start_latitude float The beginning or “pickup” latitude (required).
start_longitude float The beginning or “pickup” longitude (required).
start_address string The beginning or “pickup” address.
start_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.
start_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.
start_place.zone_id string 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_latitude float The final or destination latitude (required).
end_longitude float The final or destination longitude (required).
end_address string The final or destination address.
end_place.place_id string The place ID in provider’s namespace.
end_place.provider string 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. If none is provided, the request for a ride will be created immediately.
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 Uber will call riders with trip details if this option is enabled (optional).
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.
Response
Example response
{
  "guest": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone_number": "+14155550000"
  },
  "product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
  "request_id": "e249c871-7711-4c26-b06c-679cbad6a7c2",
  "status": "processing"
}
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 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.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.
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.

A fare_id can also expire if the time between the estimate and trip request is too long.

fare_display could be null if fares are unavailable.

Error metadata fields Type Description
fare_id string A new unique fare ID that should be used to re-request the ride.
fare_display string The price estimate range. 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
  }
}

Uber

Developers
© 2023 Uber Technologies Inc.