Driver Queues

Taxi & Private Hire › Products › Dispatch › Driver Queues

Generally available

Queues are ordered driver lists scoped to one or more zones. Drivers join a queue by signalling availability in-zone; trips entering the zone are offered to queue members in priority order. Each queue has a join-priority filter (decision tree determining who can enter), a trip-entry filter (which trips this queue handles), and join/depart rules. Supports both first-in-first-out and dispatch-time-boost ordering.

Example request

POST /client/{clientId}/queue ▷ Try it

{
  "ref": "<string>",
  "name": "<string>",
  "priority": 0,
  "joinPriority": 0,
  "tripEntryDecisionTree": {},
  "fleets": [
    {
      "id": "<id>"
    }
  ],
  "isDefault": false,
  "backupQueueGroups": [
    {
      "id": "<id>"
    }
  ]
}

Example shape, derived from the Queue fields — indicative, not the authoritative schema (that arrives with the API reference).

Endpoints

Method	Path
POST	/client/{clientId}/queue/{queueId}/fleet/{fleetId}	▷ Try it
POST	/client/{clientId}/queue · primary	▷ Try it
DELETE	/client/{clientId}/queue/{queueId}/fleet/{fleetId}	▷ Try it
GET	/client/{clientId}/queue/{queueId}	▷ Try it
POST	/client/{clientId}/queue/{queueId}/modify_column_priority	▷ Try it
POST	/client/{clientId}/queue/{queueId}	▷ Try it

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

Use cases

Operator flows that exercise this feature.

Configure a driver queue

config risk: low

Create a driver queue and set its column-priority ordering.

1. POST /client/{clientId}/queue
2. POST /client/{clientId}/queue/{queueId}/modify_column_priority

Settings

How operators configure this feature.

Decide what makes a driver the best match

When several drivers could take a trip, something has to break the tie. This lets you weight what matters to your business — closeness to the pickup, sharing work fairly, who's been waiting longest, and who's already heading that way — so the engine picks drivers the way you would.

Setting	Range	Default
Fairness time window (h) How many recent hours of earnings are compared to share work fairly.	1–12	4
Closeness importance How much being near the pickup counts when choosing a driver.	0–100	50
Fairness importance How much sharing work evenly counts when choosing a driver.	0–100	25
Waiting-time importance How much a driver's waiting time counts when choosing a driver.	0–100	15
Heading-toward importance How much it counts that a driver is already driving toward the pickup.	0–100	10
Assumed speed when maps are down (km/h) Speed used to estimate how soon a driver can arrive if live routing is briefly unavailable.	10–120	54

Related

• Dispatch Zones
• Zone Entry Queueing
• Target Zones

Fields

Field	Type	Description
ref	string	Short tenant-defined queue reference ("Q1", "AP-ARRIVE"). Stable across renames; surfaces in dispatch traces and the driver app.
name	string	Human-readable queue name shown on the operator console and driver app. Queryable via `queryFields()`.
priority	int	Dispatch-time queue priority within the tenant (lower = higher precedence). Unique by `(clientId, priority)` so two queues never tie when a trip is being offered. Different from `joinPriority`, which governs which queue a driver can enter.
joinPriority	int	Join-time priority — controls which queue a driver lands in when they're eligible for several. Unique by `(clientId, joinPriority)`; lower value = preferred queue. Drives the "stay in your top-tier queue" behaviour even after a driver crosses into a zone served by multiple queues.
tripEntryDecisionTree	JsonStorage	JsonCondition decision tree (stored via JsonStorage) deciding whether a given trip is eligible for this queue. Evaluated at trip queue-entry time against trip fields (priority, capabilities, fleet, etc.). Null = the queue accepts all trips from its fleets.
fleets	Collection	Fleets this queue serves. A trip originating from a fleet without a matching queue cannot be queue-dispatched; the inverse side lives on `Fleet.queues`.
isDefault	bool	Exactly one queue per tenant carries `isDefault=true` (UNIQ_IDENTIFIER_DEFAULT_QUEUE). Acts as the catch-all when no other queue's `tripEntryDecisionTree` matches. Setter is intentionally inert — system uses `_setIsDefault()` to bypass external mutation via the serializer.
backupQueueGroups	Collection	Ordered backup queue groups feeding eligibility expansion for trips originated on this queue. When a group's releaseTimeSeconds elapses, its queues are added to the trip's eligible-queue pool.
clientId	bigint	Tenant scope. Every tenant-aware entity carries this; `ClientFilter` enforces row-level isolation on read; the multi-tenancy routing layer (`/client/{clientId}`) sets it at create time. Surfaced only under `admin` / `tripLog` groups — never to end users.
internalKey	string	Optional client-supplied external reference / idempotency key. When present, lets external systems correlate platform-side records back to their own source-of-truth ids. Not persisted to a column — populated by the request handler when the caller sets it.
__objectType	string	Discriminator string (entity class short-name) emitted alongside the id in serialized output. Resolved at read time by `getObjectType()`; lets the FE dispatch entity-specific rendering without inspecting the URL.
id	bigint	Snowflake-style primary key (unsigned BIGINT). Generated by `IdFactory` at create time; surfaced to the FE / API as a `G`-prefixed string and stripped back to plain bigint server-side before Doctrine lookup.
createdDate	integer	Unix timestamp the row was first persisted. Set in the entity's PrePersist hook; never rewritten on subsequent updates.
updatedDate	integer	Unix timestamp the row was last touched. Bumped on every commit that hits the Doctrine UoW for this entity; drives FE invalidation + the listing change cursor.
passiveUpdatedDate	int	Read-through alias for `updatedDate` exposed under different serializer groups. Lets the FE distinguish "real edit" from "background touch" projections without changing the underlying column.
listingUpdatedDate	int	Listing-projection timestamp surfaced only under the `listMode` group. Driven by `TripCache` and other listing-shape refreshers separately from `updatedDate` so a listing rebuild doesn't trigger detail-page invalidation.