Drivers

Taxi & Private Hire › Products › Fleet › Drivers

Generally available

A Driver is the worker entity — the person who operates a Vehicle. Carries personal details (name, DoB, contact info), authentication credentials (linked via Transporter), compliance state (active/suspended/inactive), capability set, document attachments, and optional preferences (SCPs they regularly transport, favourite customers). Drivers are dispatched to trips via the Transporter session — a Driver + Vehicle pairing currently on-shift.

Example request

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

{
  "firstName": "<string>",
  "lastName": "<string>",
  "transporter": {
    "id": "<id>"
  },
  "password": "<string>",
  "homeFleet": {
    "id": "<id>"
  },
  "permittedFleets": [
    {
      "id": "<id>"
    }
  ],
  "ownedVehicles": [
    {
      "id": "<id>"
    }
  ],
  "clientCapabilities": [
    {
      "id": "<id>"
    }
  ],
  "primaryGroup": "<string>",
  "ref": "<string>",
  "trusted": false,
  "photo": {
    "id": "<id>"
  },
  "driverDocuments": [
    {
      "id": "<id>"
    }
  ],
  "scpPreferences": [
    {
      "id": "<id>"
    }
  ],
  "customerPreferences": [
    {
      "id": "<id>"
    }
  ],
  "email": "<string>",
  "phone": "<string>",
  "secondaryPhone": "<string>",
  "dateOfBirth": 0,
  "nextOfKinName": "<string>",
  "nextOfKinPhone": "<string>",
  "nextOfKinEmail": "<string>",
  "companyNumber": "<string>",
  "taxNumber": "<string>",
  "streetAddress": "<string>",
  "addressArea": "<string>",
  "city": "<string>",
  "state": "<string>",
  "postCode": "<string>",
  "country": "<string>",
  "iban": "<string>",
  "bic": "<string>",
  "driverNote": "<string>",
  "managementNote": "<string>",
  "groups": [
    {
      "id": "<id>"
    }
  ]
}

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

Endpoints

Method	Path
POST	/client/{clientId}/driver/{driverId}/clientcapability/{capabilityId}	▷ Try it
POST	/client/{clientId}/driver · primary	▷ Try it
DELETE	/client/{clientId}/driver/{driverId}/clientcapability/{capabilityId}	▷ Try it
GET	/client/{clientId}/driver/{driverId}	▷ Try it
GET	/client/{clientId}/driver	▷ Try it
POST	/client/{clientId}/driver/{driverId}	▷ Try it
POST	/client/{clientId}/driver/{driverId}/vehicle/{vehicleId}	▷ Try it
POST	/client/{clientId}/driver/{driverId}/fleet/{fleetId}	▷ Try it
DELETE	/client/{clientId}/driver/{driverId}/vehicle/{vehicleId}	▷ Try it
DELETE	/client/{clientId}/driver/{driverId}/fleet/{fleetId}	▷ 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.

Grant a driver capability

config risk: low

Assign a capability (wheelchair training, language, etc.) to a driver.

1. POST /client/{clientId}/driver/{driverId}/clientcapability/{capabilityId}

Onboard a driver

config risk: low

Register a new driver and attach their compliance documents.

1. POST /client/{clientId}/driver
2. POST /client/{clientId}/driver/{driverId}/driverdocument

Related

• Driver Documents
• Driver Sessions
• Favourite Drivers
• Approved SCP Drivers

Fields

Field	Type	Description
firstName	string	Given name. Used everywhere a human-readable driver label is shown — operator dispatch board, driver-app login screen, customer receipts.
lastName	string	Family name. Combined with firstName + photo on driver-detail screens; customer-facing payloads may show only firstName + last initial.
transporter	Transporter	Active Transporter session — the Driver + Vehicle + Fleet triple that's currently on-shift. Inverse-side relation: a Driver may have zero (off-shift) or one (on-shift) Transporter at a time.
password	string	Hashed driver-side login password. Write-only — never serialised outbound. Set via the one-time operator-issued password-reset flow. NULL while a Driver is still on the legacy Transporter-shift-password path.
homeFleet	Fleet	The fleet this driver works under for dispatch, payroll and branding.
permittedFleets	Collection	Cross-fleet work permits — additional Fleets this Driver may accept dispatch from. Disjoint from homeFleet (invariant §5.1).
ownedVehicles	Collection	Vehicles this driver owns and may operate (Mode B / owner-operator fleets only).
clientCapabilities	Collection	Driver-borne capabilities — skills/certifications the driver brings to the trip (medical-transport, sign-language, K9-handler, etc.). Combined with the active Vehicle's capabilities to form the Transporter capability bitmask used at dispatch.
primaryGroup	string	Free-text ACL grouping label — scopes which operators can see this driver. Empty = visible to everyone with general fleet access.
ref	string	Unique identifier — typically the badge / fleet number used in radio communication and dispatch chat. Visible on every operator screen as the primary driver handle.
trusted	bool	Trusted-driver flag — when true the driver can force-override arrival / no-show guards (proximity, wait-time, etc.). Used for tenured drivers whose judgement is trusted to bypass strict procedure.
photo	Document	Driver headshot — shown on the customer receipt and on the operator dispatch board for quick visual ID. Stored as a Document; uploaded via the standard presigned URL flow.
driverDocuments	Collection	Compliance documents — licences, certifications, training certificates. Each carries its own expiry; the operator console flags upcoming expiries on the driver row.
scpPreferences	Collection	Approved-SCP rows — the Special Category Passengers this driver is cleared to transport. HARD entries lock dispatch to these drivers only; SOFT entries are preferred but not required.
customerPreferences	Collection	Favourite-customer pairings — customers who have requested this specific driver. Dispatch boosts within a soft window; HARD entries strictly require the pairing.
email	string
phone	string
secondaryPhone	string
dateOfBirth	int	Driver date of birth (Unix). Feeds compliance / age-verification checks and licence-eligibility reporting; not surfaced to customers.
nextOfKinName	string	Emergency-contact name. The `nextOfKin*` trio is operator-only HR/safety data — never exposed to customers or the dispatch pipeline.
nextOfKinPhone	string	Emergency-contact phone. See `nextOfKinName`.
nextOfKinEmail	string	Emergency-contact email. See `nextOfKinName`.
companyNumber	string	Registered company / business number where the driver operates as an owner-driver or contractor entity. Jurisdiction-dependent format; used for payout compliance.
taxNumber	string	Tax / VAT registration number for the driver's payout entity. Surfaced on payout statements for tax compliance.
streetAddress	string
addressArea	string
city	string
state	string
postCode	string
country	string
iban	string	IBAN for driver payout. Stored verbatim — formatting / validation lives on the FE.
bic	string	BIC / SWIFT code paired with `iban` for international driver payouts.
driverNote	string	Notes shared with the Driver and Operator, to be treated as publicly visible and not to include personal information
managementNote	string	Internal notes for management use only.
groups	Collection
deletedAt	integer
deletedBy	bigint
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.