¶ 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 pickup_time. New features are under development to make it easier to know when the driver is given the trip offer.

¶ Authorization

OAuth 2.0 Bearer token with the health scope.

¶ Ride Types

¶ Example Requests

For Sandbox only, the run_id will be needed to be passed in as a header (e.g, -H "x-uber-sandbox-runuuid:4c11a40a-950a-4486-baf4-59858300190b") to take interactive trips.

¶ Example Request for a Ride on Demand

curl -X POST \
  -H 'authorization: Bearer $UBER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "guest" : {
  	  "email": "joe@example.com",
      "first_name": "Joe",
      "last_name": "Example",
      "phone_number": "+15551234567"
    },
    "product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
    "pickup": {
      "latitude": 37.776,
      "longitude": -122.417
    },
    "dropoff": {
      "latitude": 37.789,
      "longitude": -122.4
    },
    "contacts_to_notify" : [
      {
          "phone_number": "+14155550001",
          "contact_event": ["TRIP_BEGAN"]
      },
      {
          "phone_number": "+14155550002",
          "contact_event": ["DRIVER_PICKUP_COMPLETED"]
      }
    ]
  }' \
  'https://sandbox-api.uber.com/v1/health/trips'

¶ Example Request for an Hourly Ride

curl -X POST \
  -H 'authorization: Bearer $UBER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "guest" : {
      "email": "joe@example.com",
      "first_name": "Joe",
      "last_name": "Example",
      "phone_number": "+15551234567"
    },
    "product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
    "pickup": {
      "latitude": 37.776,
      "longitude": -122.417
    },
    "dropoff": {
      "latitude": 37.789,
      "longitude": -122.4
    },
    "contacts_to_notify" : [
      {
          "phone_number": "+14155550001",
          "contact_event": ["TRIP_BEGAN"]
      },
      {
          "phone_number": "+14155550002",
          "contact_event": ["DRIVER_PICKUP_COMPLETED"]
      }
    ],
    "hourly_params": {
      "time_in_mins": 120,
      "distance": 30,
      "distance_unit": "MILE"
    },
    "scheduling": {
      "pickup_time": 1698439444000
    }
  }' \
  'https://sandbox-api.uber.com/v1/health/trips'

¶ Request body parameters

¶ Guest object parameters Back to top

¶ Pickup object parameters Back to top

¶ Dropoff object parameters Back to top

¶ Scheduling object parameters Back to top

¶ Contacts_to_notify object parameters Back to top

¶ Return_trip_params object parameters Back to top

¶ Hourly_params object parameters Back to top

¶ Example Response

{
  "eta": 7,
  "guest": {
    "email": "joe@example.com",
    "first_name": "Joe",
    "guest_id": "OVmNxPG1ENYSwn8QonwLapF3ZJl2KJipkUc0AP3C74U=",
    "last_name": "Example",
    "phone_number": "+15551234567"
  },
  "product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
  "request_id": "def481ba-f21b-43f8-9ab3-5bdbc603af0c",
  "status": "processing"
}

¶ Pickup object response

The following table provides a detailed breakdown of the pickup location.

¶ 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. The request will fail with a 409 status code and the error body will include a fare_id to use in a subsequent trip request. 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.

To avoid 409 errors altogether, you can get a current fare_id from the /trips/estimates call and pass it in with your trip request. By passing in the fare_id, it means you are implicitly accepting the current surge, since it is already present in the estimate that you received.

¶ Error Metadata

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