Rides

A ride is one trip by one vehicle: where to go, which vehicle, and its status, from planned through in_progress and arrived to archived once it’s closed. Ambula numbers rides itself, per company.

The driver’s steps (on the way, on site, closing) belong to the driver app and aren’t part of v1. Through the API you plan rides and change what a dispatcher can change.

List rides

GET/v1/rides

Requires the scope rides:read.

Available from phase 1

The company's rides, newest first.

Query parameters

statusstring

planned, in_progress, arrived or archived.

conversation_idstring

Only the ride planned from this conversation.

assignment_idstring

Only the rides of this assignment.

created_afterISO 8601

Only records created after this time.

created_beforeISO 8601

Only records created before this time.

updated_afterISO 8601

Only records changed after this time. For a sync, pass your last sync time minus 60 seconds and deduplicate by id.

limitinteger

Page size, 1 to 100. Default 25.

cursorstring

The next_cursor of the previous page.

Request

curl "https://api.ambula.nl/v1/rides?status=planned&limit=1" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "r_7Hq2xV",
      "ride_number": 1042,
      "status": "planned",
      "ride_type": "A2",
      "direction": "outbound",
      "conversation_id": "c_93kLm0",
      "assignment_id": null,
      "vehicle_id": "v_amb2",
      "location": {
        "address": "Dorpsstraat 1, Utrecht",
        "latitude": 52.0907,
        "longitude": 5.1214
      },
      "created_at": "2026-11-09T08:14:03Z",
      "updated_at": "2026-11-09T08:20:41Z"
    }
  ],
  "next_cursor": "WzE3MzEx…"
}

Get a ride

GET/v1/rides/{id}

Requires the scope rides:read.

Available from phase 1

One ride. The response has an ETag header to send as If-Match when you change it.

Request

curl "https://api.ambula.nl/v1/rides/r_7Hq2xV" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "id": "r_7Hq2xV",
  "ride_number": 1042,
  "status": "planned",
  "ride_type": "A2",
  "direction": "outbound",
  "conversation_id": "c_93kLm0",
  "assignment_id": null,
  "vehicle_id": "v_amb2",
  "location": {
    "address": "Dorpsstraat 1, Utrecht",
    "latitude": 52.0907,
    "longitude": 5.1214
  },
  "created_at": "2026-11-09T08:14:03Z",
  "updated_at": "2026-11-09T08:20:41Z"
}

List a ride's photos

GET/v1/rides/{id}/photos

Requires the scope rides:read.

Available from phase 1

Photos the driver took while closing the ride, as signed links valid for 15 minutes.

Request

curl "https://api.ambula.nl/v1/rides/r_7Hq2xV/photos" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "ph_1",
      "url": "https://storage.googleapis.com/…",
      "thumbnail_url": "https://api.ambula.nl/v1/media/ph_1/thumbnail",
      "width": 2048,
      "height": 1536,
      "taken_at": "2026-11-09T09:40:00Z"
    }
  ],
  "next_cursor": null
}

Plan a ride

POST/v1/rides

Requires the scope rides:write.

Available from phase 2

Plan a ride. Ambula assigns the next ride number. With conversation_id, a conversation gets at most one ride: a second request returns the first ride with 200.

Side effect. Assigning a vehicle sends the vehicle's driver a push notification and a WhatsApp message.

Body

titlestringrequired

What the ride is for.

ride_typestring

A ride type code. Default: the company's default type.

vehicle_idstring

Assign a vehicle now, or later with an update.

conversation_idstring

The conversation this ride is for.

locationobject

Where to go. From a conversation, defaults to the pickup contact or the conversation's location.

dateISO 8601

When the ride is planned for.

Request

curl -X POST "https://api.ambula.nl/v1/rides" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Idempotency-Key: 4f1c9a2e-…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Kat vast in boom","conversation_id":"c_93kLm0"}'

Response · 201

{
  "id": "r_7Hq2xV",
  "ride_number": 1042,
  "status": "planned",
  "ride_type": "A2",
  "direction": "outbound",
  "conversation_id": "c_93kLm0",
  "assignment_id": null,
  "vehicle_id": null,
  "location": {
    "address": "Dorpsstraat 1, Utrecht",
    "latitude": 52.0907,
    "longitude": 5.1214
  },
  "created_at": "2026-11-09T08:14:03Z",
  "updated_at": "2026-11-09T08:20:41Z"
}

Update a ride

PATCH/v1/rides/{id}

Requires the scope rides:write.

Available from phase 2

Change the dispatcher's fields of a ride. A driver's steps (on the way, on site, closing) stay with the driver app and answer 422. Send If-Match with the ETag from your last read; a conflicting change answers 412.

Side effect. Assigning a vehicle sends the vehicle's driver a push notification and a WhatsApp message.

Body

vehicle_idstring | null

Assign or unassign a vehicle.

ride_typestring

A ride type code.

locationobject

Where to go.

instructionsstring

Shown to the driver.

Request

curl -X PATCH "https://api.ambula.nl/v1/rides/r_7Hq2xV" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "If-Match: \"1731140441\"" \
  -H "Content-Type: application/json" \
  -d '{"vehicle_id":"v_amb2"}'

Response · 200

{
  "id": "r_7Hq2xV",
  "ride_number": 1042,
  "status": "planned",
  "ride_type": "A2",
  "direction": "outbound",
  "conversation_id": "c_93kLm0",
  "assignment_id": null,
  "vehicle_id": "v_amb2",
  "location": {
    "address": "Dorpsstraat 1, Utrecht",
    "latitude": 52.0907,
    "longitude": 5.1214
  },
  "created_at": "2026-11-09T08:14:03Z",
  "updated_at": "2026-11-09T08:31:00Z"
}

Delete a ride

DELETE/v1/rides/{id}

Requires the scope rides:write.

Available from phase 2

Delete a ride. Its number is not reused. Emits ride.deleted.