Deliveries (Rides) API Reference

Looking for every endpoint and schema in one place? See the Full OpenAPI reference.

Endpoints

Method and path	What it does	Key permission
`GET /api/v1/rides`	List Rides Query: status	`rides:read`
`GET /api/v1/rides/{id}`	Get Ride Details	`rides:read`
`POST /api/v1/rides`	Create Ride	`rides:write`
`PUT /api/v1/rides/{id}`	Update a ride	`rides:write`
`PATCH /api/v1/rides/{id}/pickup-complete`	Mark Pickup as Complete	`rides:write`
`PATCH /api/v1/rides/{id}/pickup/verify`	Verify pickup with OTP code	`rides:write`
`PATCH /api/v1/rides/{id}/delivery/verify`	Verify delivery with OTP code	`rides:write`
`DELETE /api/v1/rides/{id}`	Delete a ride	`rides:delete`
`POST /api/v1/rides/{id}/assign-driver`	Assign Driver to Ride	`rides:write`
`GET /api/v1/rides/{id}/trail`	Driver GPS trail for a delivery Query: page, limit	`rides:read`
`GET /api/v1/rides/{id}/timeline`	Status history with actors and detected trip events	`rides:read`
`GET /api/v1/rides/{id}/updates`	What the customer was told on the tracking page	`rides:read`
`POST /api/v1/rides/{id}/updates`	Send the customer a message on their tracking page	`rides:write`
`GET /api/v1/rides/{id}/share-message`	Ready-to-paste text with the tracking link	`rides:read`

Creating a delivery

Required fields:

Field	Type	Notes
`customer_name`	string	At least 2 characters.
`address`	string	Delivery address, at least 5 characters. Geocoded on the server.
`pickup_address`	string	At least 5 characters.
`pickup_contact_name`	string	At least 2 characters.
`pickup_phone`	string	Read in your company’s country.
`estimated_pickup_time`	ISO date-time	Must be in the future.

Useful optional fields: phone_number and email (the recipient; email triggers the booking email), order_id (your reference), notes, items_count, item_type, item_weight, is_fragile, requires_signature, latitude/longitude and pickup_latitude/pickup_longitude if you already know them, zone_id, and driver_id to assign straight away.

The delivery is created as pending, then assigned if you passed driver_id, then started if you passed "status": "in_progress". If assignment is refused the delivery still exists and is returned in ride on the error. The response includes public_tracking_token; the customer’s page is https://trackthatride.com/track/<public_tracking_token>.

Listing and filtering

GET /api/v1/rides accepts page, limit (default 50, maximum 100), status, driver_id, zone_id, search (customer name or phone), date_from and date_to (on the estimated pickup time), has_driver, pickup_completed, sortBy (created_at, customer_name, status, estimated_pickup_time) and sortOrder. The response is { "rides": [...], "pagination": {...}, "filters": {...} }.

Status and the delivery lifecycle

Statuses: pending → assigned → in_progress → delivered or failed; failed → assigned for another attempt; cancelled from any status that is not final; assigned → pending to unassign. Change status with PUT /api/v1/rides/{id} and a body such as { "status": "failed", "reason": "Recipient not available" }.

The same rules apply as in the dashboard, and refusals return a code:

Status	`code`	Meaning
400	`INVALID_STATUS`	Not a known status.
409	`INVALID_TRANSITION`	That change is not allowed from the current status.
409	`DRIVER_BUSY`	The driver already has the maximum number of deliveries in progress.
409	`NO_DRIVER`	A driver is needed for this change.
402	`INSUFFICIENT_FUNDS`, `BILLING_ERROR`	Starting the delivery needs a wallet top-up (see pricing).

Starting a delivery (moving it to in_progress) is the billable event.

Assigning a driver

curl -X POST https://trackthatride.com/api/v1/rides/123/assign-driver \
  -H "Authorization: Bearer $TTR_API_KEY" -H "Content-Type: application/json" \
  -d '{"driver_id": 45}'

Returns { "message", "ride", "driver": { "id", "name", "phone", "vehicle_type", "vehicle_id" } }. Errors: DRIVER_NOT_FOUND (400), DRIVER_INACTIVE (409), INVALID_TRANSITION (409). A driver with queued deliveries can be assigned more; only deliveries in progress are limited.

Messages to the customer

POST /api/v1/rides/{id}/updates posts a message to the customer’s tracking page; GET on the same path lists what the customer was told and when they saw it. GET …/share-message returns ready-to-paste text with the tracking link.

After the delivery

GET …/timeline returns the status history with who made each change and detected trip events (arrived at pickup, departed, arrived at drop-off). GET …/trail returns the driver’s recorded positions for the delivery, paginated with page and limit; positions are kept for 180 days unless the delivery is on audit hold.

Proof-of-delivery files are not exposed as v1 endpoints yet; the delivery.completed webhook carries the proof with links valid for 24 hours.

Deliveries (rides) API