Rides
Booking a ride from another system: how it is sent, how not to duplicate it and how to follow it until it finishes.
When a hotel guest, a patient or an employee needs a ride and the booking starts in another system, the ride still has to enter the same queue as all the others — without losing or duplicating anything.
Ride statuses
| Status | Means | Final |
|---|---|---|
REQUESTED | The ride is booked and waits for assignment | no |
OFFERED | An offer was sent to a driver and waits for acceptance | no |
ASSIGNED | The ride has a driver who has not confirmed yet | no |
ACCEPTED | The driver accepted | no |
ARRIVING | The driver is on the way to the passenger | no |
ARRIVED | The driver arrived; waiting time runs | no |
IN_PROGRESS | The passenger is on board | no |
COMPLETED | The ride is finished; the final price is known | yes |
CANCELLED | The ride was cancelled (by either side) | yes |
NO_SHOW | The driver arrived, the passenger was not there | yes |
FAILED | The ride failed for a technical reason | yes |
Booking a ride
Creates a ride. Scope book. When both coordinates are sent, distance and duration are optional — the server computes them from the route.
| Field | Type | Required | Description |
|---|---|---|---|
externalId | string (2–80) | — | Idempotency key, unique inside the company; the same request twice does not create two rides |
serviceTypeId | uuid | ✓ | From GET /v1/service-types |
vehicleClassId | uuid | — | If the company uses vehicle classes |
paymentMethod | enum | — | CASH, CARD, TERMINAL, WALLET, CORPORATE_ACCOUNT, INVOICE |
passengerName | string (2–160) | — | Passenger name for the driver and the receipt |
passengerPhone | string | — | Phone in international or local format |
pickupAddress | string (2–300) | ✓ | The pickup address the driver sees |
pickupLatitude / pickupLongitude | number | ✓ | Pickup coordinates (7 decimals) |
dropoffAddress | string (2–300) | — | Destination; without it the ride is open-ended |
dropoffLatitude / dropoffLongitude | number | — | Destination coordinates |
distanceKm / durationMinutes | number | — | If sent, the server does not compute them again |
scheduledAt | ISO 8601 | — | A ride booked ahead (module addon.scheduled_rides) |
notes | string (≤1000) | — | A note for the driver |
couponCode | string (≤40) | — | Promo code (module addon.promo_codes) |
corporateAccountId / costCenterId | uuid | — | Corporate account and cost centre (module addon.corporate_accounts) |
stops | array (≤16) | — | Intermediate stops: address, latitude, longitude |
curl -s -X POST https://driveos.eu/api/v1/rides \
-H "X-API-Key: $DEMO_TAXI_KEY" \
-H 'Content-Type: application/json' \
-d '{
"externalId": "erp-2026-000417",
"serviceTypeId": "8f1c2a6e-6d4b-4f2a-9d31-2a7c1b6e5f01",
"paymentMethod": "CARD",
"passengerName": "Ana Anić",
"passengerPhone": "+385 91 555 0100",
"pickupAddress": "Ilica 42, 10000 Zagreb",
"pickupLatitude": 45.8127,
"pickupLongitude": 15.9700,
"dropoffAddress": "Zračna luka Zagreb, 10150 Zagreb",
"dropoffLatitude": 45.7429,
"dropoffLongitude": 16.0688,
"notes": "Dva kofera",
"scheduledAt": "2026-11-18T04:30:00Z"
}'
{
"ride": {
"number": "R-2026-000417",
"status": "REQUESTED",
"channel": "API",
"requestedAt": "2026-11-17T08:12:00.000Z",
"scheduledAt": "2026-11-18T04:30:00.000Z",
"pickupAddress": "Ilica 42, 10000 Zagreb",
"dropoffAddress": "Zračna luka Zagreb, 10150 Zagreb",
"estimatedPrice": 24.80,
"finalPrice": null,
"currencyCode": "EUR",
"externalId": "erp-2026-000417",
"serviceType": { "code": "STANDARD", "name": "Standard" },
"driver": null
},
"replayed": false
}
externalId again returns replayed: true and the same ride — no new one is created. That is the only safe way to repeat a request after a dropped connection without duplicating a ride.List and detail
The company’s ride list. Scope rides. Without filters it returns the latest 25 by booking time.
| Field | Type | Required | Description |
|---|---|---|---|
page / pageSize | integer | — | Pagination; pageSize at most 100, default 25 |
status | string | — | One or more statuses, comma separated |
from / to | date | — | Range by booking time (YYYY-MM-DD) |
updatedSince | ISO 8601 | — | Every ride changed after that moment — for sync |
serviceTypeId / driverId | uuid | — | Filters by service type and driver |
q | string | — | Search by number, address or passenger name |
externalId | string | — | An exact external identifier |
Ride detail with stops and the status timeline. Scope rides. A ride of another company returns 404, not 403.
Cancellation
Cancels a ride. Scope book. A finished ride returns 409. The reason is optional but is recorded in history and shown to the dispatcher.
| Field | Type | Required | Description |
|---|---|---|---|
reason | string (≤200) | — | Cancellation reason (e.g. “Passenger cancelled”) |
curl -s -X POST https://driveos.eu/api/v1/rides/R-2026-000417/cancel \
-H "X-API-Key: $DEMO_TAXI_KEY" \
-H 'Content-Type: application/json' \
-d '{"reason":"Putnik je otkazao"}'
Common errors
| Code | Status | Cause |
|---|---|---|
errors.apiRideNeedsRoute | 400 | Not enough data for a route (an address without coordinates) |
errors.invalidPhone | 400 | The phone is not in a recognised format |
errors.externalIdInvalid | 400 | The external id contains disallowed characters |
errors.tooManyStops | 400 | More than 16 intermediate stops |
errors.serviceTypeMissing | 400 | The service type does not exist or is not active (errors.serviceTypeInactive) |
errors.rideTransitionNotAllowed | 409 | The ride is in a state from which it cannot be cancelled (e.g. already finished) |
errors.launchNotReady | 400 | The company is not ready to operate yet (see the readiness gate) |