Skip to content
Go

Trips

Taxi & Private Hire › Products › Trip › Trips

Generally available

A Trip is the top-level booking record on the platform. It carries pickup and dropoff details, customer reference, scheduled or ASAP timing, lifecycle status, derived dispatch metadata (pickup zone, H3 cell), pricing mode, and links to its segments. Operators create trips through the console; drivers receive offers based on dispatch scoring; customers see the trip in their app or via tracking links.

Example request

POST /client/{clientId}/trip 

{
  "pricingMode": "METERED",
  "tripSegments": [
    {
      "customer": {
        "phone": "<E.164 phone>"
      },
      "tripSegmentStops": [
        {
          "type": "PICKUP",
          "pickupAddress": "<address>",
          "pickupLatitude": "<lat>",
          "pickupLongitude": "<lng>"
        },
        {
          "type": "DROPOFF",
          "pickupAddress": "<address>",
          "pickupLatitude": "<lat>",
          "pickupLongitude": "<lng>"
        }
      ],
      "requestedPickupDate": "<unix-seconds>"
    }
  ],
  "maxSeatCapacity": "<seats>"
}

Endpoints

MethodPath
POST /client/{clientId}/trip · primary
GET /client/{clientId}/trip
POST /client/{clientId}/trip/{tripId}/assign/{transporterId}
POST /client/{clientId}/trip/{tripId}/reclaim
POST /client/{clientId}/trip/{tripId}/designate
DELETE /client/{clientId}/trip/{tripId}/designate
POST /client/{clientId}/trip/{tripId}/status
POST /client/{clientId}/trip/{tripId}/health/resolve
GET /client/{clientId}/rejected-trip
POST /client/{clientId}/trip/{tripId}/copy
GET /client/{clientId}/trip/{tripId}
GET /client/{clientId}/trip/{tripId}/dispatch-audit/{transporterId}
GET /client/{clientId}/trip/{tripId}/dispatch-log
POST /client/{clientId}/trip/{tripId}/edit/release
POST /client/{clientId}/trip/{tripId}/guard-override
GET /client/{clientId}/trip/{tripId}/guard-status
GET /client/{clientId}/trip/{tripId}/health
GET /client/{clientId}/trip/{tripId}/logs
POST /client/{clientId}/trip/merge
POST /client/{clientId}/trip/merge/analyze
POST /client/{clientId}/trip/{tripId}/merge/candidates
POST /client/{clientId}/trip/{tripId}
GET /client/{clientId}/trip/count
GET /client/{clientId}/trip/optimizable
GET /client/{clientId}/trip/optimizable-accounts
GET /client/{clientId}/trip/sync

Full request/response schemas and an interactive explorer will live in the API reference (coming soon).

Use cases

Operator flows that exercise this feature.

Create a booking

action risk: low

Take a new ASAP booking — optionally quote first, then create the trip.

  1. POST /client/{clientId}/quote/trip
  2. POST /client/{clientId}/trip
Book on a corporate account

action risk: low

Create a trip billed to a corporate account rather than the individual rider.

  1. POST /client/{clientId}/trip
Force-assign a driver

action risk: medium

Immediately assign a trip to a chosen driver (force-now) — distinct from designate, which reserves through allocation.

  1. POST /client/{clientId}/trip/{tripId}/assign/{transporterId}
Reclaim a trip from a disconnected driver

action risk: low

Detect a trip whose assigned driver has gone stale (lost GPS / disconnected) and reclaim it back to allocation so it can be re-dispatched.

  1. POST /client/{clientId}/trip/{tripId}/health/resolve
  2. POST /client/{clientId}/trip/{tripId}/reclaim
Manual dispatch (designate a driver)

action risk: low

Operator manually dispatches a trip by designating a chosen driver, who then holds the trip through allocation (the engine reserves/offers to them rather than dispatching openly). Industry "manual dispatch" lives on the designate endpoint.

  1. POST /client/{clientId}/trip/{tripId}/designate
Clear a designation

action risk: low

Remove a manual driver designation so the trip returns to open dispatch.

  1. DELETE /client/{clientId}/trip/{tripId}/designate
Cancel a booking

action risk: low

Cancel a trip. Cancel is NOT its own endpoint — it is a status transition to CANCELLED (Finding 1). If you only have a passenger name / destination, resolve the tripId first with find-trip.

  1. POST /client/{clientId}/trip/{tripId}/status
Re-book by copying

action risk: low

Duplicate an existing trip to quickly re-book a repeat journey.

  1. POST /client/{clientId}/trip/{tripId}/copy
Diagnose allocation

read_diagnose risk: low

Explain why a trip wasn't allocated: read the dispatch audit + decision log.

  1. GET /client/{clientId}/trip/{tripId}/dispatch-audit/{transporterId}
  2. GET /client/{clientId}/trip/{tripId}/dispatch-log
Release a trip edit lock

action risk: low

Release a stuck operator edit lock on a trip so others can edit it.

  1. POST /client/{clientId}/trip/{tripId}/edit/release
Override a dispatch guard

action risk: high approval required

Override a capacity/time/proximity guard to push a trip past a block. Audit-logged; operator/system only.

  1. POST /client/{clientId}/trip/{tripId}/guard-override
Merge into a shared ride

action risk: medium

Combine compatible trips into one shared-ride vehicle: analyse compatibility, then execute the merge.

  1. POST /client/{clientId}/trip/merge/analyze
  2. POST /client/{clientId}/trip/merge
Find merge candidates

read_diagnose risk: low

Suggest nearby trips that could merge with a given trip.

  1. POST /client/{clientId}/trip/{tripId}/merge/candidates
Amend a booking

action risk: low

Modify an existing booking (pickup, time, passengers).

  1. POST /client/{clientId}/trip/{tripId}
Find a trip

read_diagnose risk: low

Look up live / scheduled trips by free-text keyword (passenger name, pickup/drop-off address, reference) to resolve a tripId — e.g. before cancelling, amending or diagnosing a trip. Reads the dispatch grid via trips_sync. The keyword is passed as a QUERY param, not a body: search is a JSON-encoded string (see trip-search-query note).

  1. GET /client/{clientId}/trip/sync