Skip to content
Go

Designated Transporters

Taxi & Private Hire › Products › Dispatch › Designated Transporters

Generally available

Operators can manually assign a trip to a specific transporter, bypassing the normal dispatch flow. The designation creates a reserved offer with its own lifecycle; the dispatch engine skips designated trips from auto-allocation. Used as a manual intervention path when automated dispatch cannot resolve a trip, and as the substrate the auto-rescue feature builds on.

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