Three lines

Uber

Developers

POST /requests

Privileged Scope This endpoint requires a privileged scope to be used in production by all Uber riders. You can use this endpoint immediately when authenticated as yourself or any of your 5 registered developers. When you are ready to distribute your application broadly for use by all Uber riders, you may request FULL ACCESS. For more information read about scopes.

Ride Request - Create

The Ride Request endpoint allows a ride to be requested on behalf of an Uber user.

See the Ride Request tutorial for a step-by-step guide to requesting rides on behalf of an Uber user. Please review the sandbox documentation on how to develop and test against these endpoints without making real-world Ride Requests and being charged.

Resource

POST /v1.2/requests

Authorization

OAuth 2.0 user access token with the request scope.

POST Parameters

This endpoint requires:

  1. Start Location
  2. End Location
  3. Fare ID

and accepts a few other parameters listed below.

Name Type Description
fare_id string The key for the upfront fare of a ride.
product_id string The unique ID of the product being requested.
Start Location Data
start_latitude float The beginning or “pickup” latitude. Either this or start_place_id must be specified.
start_longitude float The beginning or “pickup” longitude. Either this or start_place_id must be specified.
start_place_id (optional) string The beginning or “pickup” place ID. This is the name of an Uber saved place. Only “home” or “work” is acceptable. Either this or start_latitude and start_longitude must be specified.
start_nickname (optional) string The beginning or “pickup” nickname label.
start_address (optional) string The beginning or “pickup” address.
End Location Data
end_latitude float The final or destination latitude. Either this or end_place_id may be specified.
end_longitude float The final or destination longitude. Either this or end_place_id may be specified./td>
end_place_id (optional) string The final or destination place ID. This is the name of an Uber saved place. Only “home” or “work” is acceptable. Either this or end_latitude and end_longitude may be specified.
end_nickname (optional) string The final or destination nickname label.
end_address (optional) string The final or destination address.
Optional Data
surge_confirmation_id (optional) string The unique identifier of the surge session for a user. Required when returned from a 409 Conflict response on previous POST attempt.
payment_method_id (optional) string The unique identifier of the payment method selected by a user. If set, the trip will be requested using this payment method. If not set, the trip will be requested using the user’s last used payment method.
UberPOOL Data (optional)
seat_count (optional) int The number of seats required for uberPOOL. Default and maximum value is 2.
Uber For Business Data (optional)
expense_code (optional) string An alphanumeric identifier for expense reporting policies. This value will appear in the trip receipt and any configured expense-reporting integrations like Uber For Business or Business Profiles.
expense_memo (optional) string A free text field to describe the purpose of the trip for expense reporting. This value will appear in the trip receipt and any configured expense-reporting integrations like Uber For Business or Business Profiles.
Example

When specifying pickup and dropoff locations, you can either use latitude/longitude pairs or a place ID. A place ID is just the name of an Uber saved place. Currently only “home” or “work” is acceptable.

{
  "fare_id": "d30e732b8bba22c9cdc10513ee86380087cb4a6f89e37ad21ba2a39f3a1ba960",
	"product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
	"start_latitude": 37.761492,
	"start_longitude": -122.423941,
	"end_latitude": 37.775393,
	"end_longitude": -122.417546
}
{
  "fare_id": "d30e732b8bba22c9cdc10513ee86380087cb4a6f89e37ad21ba2a39f3a1ba960",
	"product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
	"start_place_id": "home",
	"end_place_id": "work"
}
Response

Status-Code: 202 Accepted

{
   "request_id": "852b8fdd-4369-4659-9628-e122662ad257",
   "product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
   "status": "processing",
   "vehicle": null,
   "driver": null,
   "location": null,
   "eta": 5,
   "surge_multiplier": null
}
Name Type Description
request_id string The unique ID of the 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 Request indicating state.
vehicle object The object that contains vehicle details.
driver object The object that contains driver details.
location object The object that contains the location information of the vehicle and driver.
eta integer The estimated time of vehicle arrival in minutes.
surge_multiplier float The surge pricing multiplier used to calculate the increased price of a Request. A multiplier of 1.0 means surge pricing is not in effect.
Error Responses

In extreme cases of fluctuating surge pricing the surge_confirmation_id could expire prematurely to the timestamp and booking the ride will result in a fare_expired error.

Status-Code: 409 Conflict

{
   "meta": {
      "surge_confirmation": {
         "href": "https:\/\/api.uber.com\/v1\/surge-confirmations\/e100a670",
         "surge_confirmation_id": "e100a670",
         "multiplier": 1.4,
         "expires_at": 1459191276
      }
   },
   "errors":[
      {
         "status": 409,
         "code": "surge",
         "title": "Surge pricing is currently in effect for this product."
      }
   ]
}
Name Type Description
surge_confirmation_id string The surge confirmation identifier used to make a Request after a user has accepted surge pricing.
href string The URL a user must visit to accept surge pricing.
multiplier float The current surge multiplier that must be accepted.
expires_at number The expiration of the surge_confirmation_id as a Unix timestamp.

In some cases the rider’s account can be in a state where requesting a ride is not allowed. Examples include riders with invalid payment methods, phone numbers, or suspected fraud.

Status-Code: 400 Bad Request

{
  "status": 400,
  "code": "invalid_mobile_phone_number",
  "title":"The rider's mobile phone number is not supported."
}
HTTP Error Codes

Below is a list of the HTTP error codes this endpoint could return.

HTTP Status Code Description
400 unconfirmed_email The user hasn’t confirmed their email address. Instruct the user to confirm their email address within the native mobile application or by visiting https://riders.uber.com.
400 error_processing_request Error processing the request.
400 error_promotions_revoked Promotions revoked.
400 invalid_payment The rider’s payment method is invalid. The user must update the billing info. This could include e.g. Android Pay.
400 invalid_payment_method The provided payment method ID is not valid.
400 outstanding_balance_update_billing The user has outstanding balances. The user must update the billing info.
400 insufficient_balance There is insufficient balance on the credit card associated with the user. The user must update the billing info.
400 payment_method_not_allowed The payment method is not allowed.
400 card_assoc_outstanding_balance The user’s associated card has an outstanding balance. The user must update the billing info.
400 invalid_mobile_phone_number The user’s mobile phone number is not supported. We do not allow phone numbers from some providers that allow the creation of temporary phone numbers.
403 forbidden This user is forbidden from making a request at this time and should consult our support team by visiting https://help.uber.com or by emailing support@uber.com.
403 unverified The user hasn’t confirmed their mobile number. Instruct the user to confirm their mobile phone number within the native mobile application or by visiting https://riders.uber.com.
403 verification_required The user currently cannot make ride requests through the API and is advised to use the Uber iOS or Android rider app to get a ride.
403 product_not_allowed The product being requested is not available to the user. Have them select a different product to successfully make a request.
403 pay_balance The rider has an outstanding balance and must update her account settings by using the native mobile application or by visiting https://riders.uber.com.
403 user_not_allowed User is banned and is not permitted to request a ride.
403 too_many_cancellations The rider is temporarily blocked due to canceling too many times.
403 missing_national_id Certain jurisdictions require Uber users to register their national ID number or passport number before taking a ride. If a user receives this error when booking a trip through the Developer API, they must enter their national ID number or passport number through the Uber iOS or Android app.
403 out_of_company_policy The time, pickup, or destination is not in compliance with the policy defined by a Uber for Business account or payment method.
404 no_product_found An invalid product ID was requested. Retry the API call with a valid product ID.
409 missing_payment_method The rider must have at least one payment method on file to request a car. The rider must add a payment method by using the native mobile application or by visiting https://riders.uber.com.
409 surge Surge pricing is currently in effect for this product. Please have the user confirm surge pricing by sending them to the surge_confirmation_href described in the Request Tutorial.
409 fare_expired The fare has expired for the requested product. Please get estimates again, confirm the new fare, and then re-request.
409 retry_request An error has occurred when the attempting to request a product. Please reattempt the request on behalf of the user.
409 current_trip_exists The user is currently on a trip.
422 invalid_fare_id This fare id is invalid or expired.
422 destination_required This product requires setting a destination for ride requests.
422 distance_exceeded The distance between start and end location exceeds 100 miles.
422 same_pickup_dropoff Pickup and Dropoff can’t be the same.
422 validation_failed The destination is not supported for uberPOOL.
422 invalid_seat_count Number of seats exceeds max capacity.
422 outside_service_area The destination is not supported by the requested product.
500 internal_server_error An unknown error has occurred.

Uber

Developers
© 2023 Uber Technologies Inc.