Backup Zones

Taxi & Private Hire › Products › Dispatch › Backup Zones

Generally available

When a primary zone has no driver supply, dispatch can fall back to a BackupZoneGroup — an ordered list of feeder zones plus a fallback dispatch mode. Each group is anchored to a feeder zone with a priority; rules (see BackupZoneGroupRule) decide which trips qualify. Lets operators configure city-wide failover patterns ("if Zone A is empty, try Zone B then Zone C with relaxed rules") without writing custom code.

Example request

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

{
  "feederZone": {
    "id": "<id>"
  },
  "defaultDispatchMode": "NONE",
  "priority": 0,
  "zones": [
    {
      "id": "<id>"
    }
  ],
  "rules": [
    {
      "id": "<id>"
    }
  ]
}

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

Endpoints

Method	Path
POST	/client/{clientId}/backupzonegroup/{backupZoneGroupId}/zone/{zoneId}	▷ Try it
POST	/client/{clientId}/backupzonegroup · primary	▷ Try it
DELETE	/client/{clientId}/backupzonegroup/{backupZoneGroupId}	▷ Try it
GET	/client/{clientId}/backupzonegroup/{backupZoneGroupId}	▷ Try it
DELETE	/client/{clientId}/backupzonegroup/{backupZoneGroupId}/zone/{zoneId}	▷ Try it
POST	/client/{clientId}/backupzonegroup/rule/{ruleId}/tripprofile/{tripProfileId}	▷ Try it
POST	/client/{clientId}/backupzonegroup/{backupZoneGroupId}/rule	▷ Try it
DELETE	/client/{clientId}/backupzonegroup/{backupZoneGroupId}/rule/{ruleId}	▷ Try it
DELETE	/client/{clientId}/backupzonegroup/rule/{ruleId}/tripprofile/{tripProfileId}	▷ Try it
POST	/client/{clientId}/backupzonegroup/{backupZoneGroupId}/rule/{ruleId}	▷ Try it
POST	/client/{clientId}/backupzonegroup/{backupZoneGroupId}	▷ Try it
POST	/client/{clientId}/backupzonegrouprule/{ruleId}/tripprofile/{tripProfileId}	▷ Try it
POST	/client/{clientId}/backupzonegrouprule	▷ Try it
POST	/client/{clientId}/backupzonegrouprule/{ruleId}/decrease-priority	▷ Try it
DELETE	/client/{clientId}/backupzonegrouprule/{ruleId}	▷ Try it
DELETE	/client/{clientId}/backupzonegrouprule/{ruleId}/tripprofile/{tripProfileId}	▷ Try it
GET	/client/{clientId}/backupzonegrouprule/{ruleId}	▷ Try it
POST	/client/{clientId}/backupzonegrouprule/{ruleId}/increase-priority	▷ Try it
POST	/client/{clientId}/backupzonegrouprule/{ruleId}	▷ 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.

Set up backup-zone fallback

config risk: medium

Create a backup-zone group and add fallback zones for when the primary empties.

1. POST /client/{clientId}/backupzonegroup
2. POST /client/{clientId}/backupzonegroup/{backupZoneGroupId}/zone/{zoneId}

Reorder a backup-zone rule

config risk: low

Raise a backup-zone rule priority to change the fallback search order.

1. POST /client/{clientId}/backupzonegrouprule/{ruleId}/increase-priority

Related

• Dispatch Zones
• Zone Fallback Policy
• Expanding Proximity Radius

Fields

Field	Type	Description
feederZone	Zone	Primary zone that delegates dispatch to this backup group when supply runs out locally. The group lives "off" this feeder zone — different feeder zones can have different backup configurations.
defaultDispatchMode	DispatchMode · NONE | PROXIMITY | PROXIMITY_FAIRNESS | QUEUE	Fallback dispatch behaviour used when no rule matches: QUEUE (queue position decides), PROXIMITY (nearest available driver), or IMMEDIATE (assign instantly to any eligible). Default QUEUE — the most common configuration.
priority	smallint	Ordering within the feeder zone — lower priority runs first. Lets operators stack multiple backup groups against one feeder zone ("try suburb backup first, then airport overflow").
zones	Collection	Pool of fallback zones — when the feeder zone exhausts supply, dispatch picks the next available transporter from any of these.
rules	Collection	Per-priority rules that override defaultDispatchMode for matching trip profiles. Evaluated in priority order; first match wins. Empty list = always use defaultDispatchMode.
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.