Ride Status

Two endpoints manage ride status: a public GET to read the current state of any ride, and an authenticated POST to drive the ride through its lifecycle. A separate GET /rides/requested endpoint lists all rides awaiting driver acceptance.

Get ride status

No authentication required — this is a public endpoint. GET /rides/status/{rideId}

number

required

The unique ID of the ride.

Response

Returns the full Ride object for the given rideId. Returns 404 if the ride does not exist.

number

Unique ride identifier.

string

Current status of the ride. One of REQUESTED, ACCEPTED, PICKED, COMPLETED, CANCELLED.

number

ID of the rider.

number

ID of the assigned driver, or null if not yet accepted.

number

Fare for the ride.

string

ISO 8601 timestamp of ride creation.

string

ISO 8601 timestamp of when a driver accepted the ride, or null.

Example

curl -X GET "http://localhost:8080/rides/status/1021"

{
  "id": 1021,
  "status": "ACCEPTED",
  "riderId": 42,
  "driverId": 7,
  "fare": 145.00,
  "createdAt": "2026-04-02T10:15:30Z",
  "acceptedAt": "2026-04-02T10:17:05Z"
}

Update ride status

Authentication required — include Authorization: Bearer <token> in the request header. POST /rides/status/{rideId}

number

required

The unique ID of the ride to update.

string

required

The target status. Must be one of ACCEPTED, PICKED, COMPLETED, or CANCELLED.

string

Required when setting status to ACCEPTED. The ID of the driver accepting the ride.

string

Required when setting status to PICKED or COMPLETED. Must match the corresponding OTP on the ride (startOtp for PICKED, endOtp for COMPLETED).

Status transitions

From	To	Required fields
`REQUESTED`	`ACCEPTED`	`driverId`
`ACCEPTED`	`PICKED`	`otp` (must match `startOtp`)
`PICKED`	`COMPLETED`	`otp` (must match `endOtp`)
Any non-terminal	`CANCELLED`	—

Response

Returns the updated Ride object with the new status applied.

Example

curl -X POST "http://localhost:8080/rides/status/1021" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ACCEPTED",
    "driverId": "7"
  }'

{
  "id": 1021,
  "status": "ACCEPTED",
  "riderId": 42,
  "driverId": 7,
  "fare": 145.00,
  "createdAt": "2026-04-02T10:15:30Z",
  "acceptedAt": "2026-04-02T10:17:05Z"
}

List requested rides

No authentication required — this is a public endpoint. GET /rides/requested Returns all rides currently in REQUESTED status. Drivers use this endpoint to discover available rides.

Response

An array of Ride objects with status: "REQUESTED".

Example

curl -X GET "http://localhost:8080/rides/requested"

[
  {
    "id": 1021,
    "status": "REQUESTED",
    "riderId": 42,
    "fare": 145.00,
    "pickupLocation": "MG Road, Bangalore",
    "dropLocation": "Indiranagar, Bangalore",
    "createdAt": "2026-04-02T10:15:30Z"
  },
  {
    "id": 1022,
    "status": "REQUESTED",
    "riderId": 55,
    "fare": 210.00,
    "pickupLocation": "Koramangala, Bangalore",
    "dropLocation": "Whitefield, Bangalore",
    "createdAt": "2026-04-02T10:18:44Z"
  }
]

Sending an invalid OTP when transitioning to PICKED or COMPLETED returns a 400 Bad Request. The status is not updated.

Authentication

Rides

Payments

Notifications & Settings

Get ride status

Response

Example

Update ride status

Status transitions

Response

Example

List requested rides

Response

Example

​Get ride status

​Response

​Example

​Update ride status

​Status transitions

​Response

​Example

​List requested rides

​Response

​Example

Get ride status

Response

Example

Update ride status

Status transitions

Response

Example

List requested rides

Response

Example