Plan endpoints

One call creates the plan, adds your stops and starts optimization across the drivers you selected.

How a stop is located

Each stop is resolved by the first of these that applies, in order:

1. addressBookEntryId — takes the coordinates and any settings you left blank from that address-book entry. It overrides any latitude/longitude you sent yourself: the entry's coordinates win.
2. A name match against the address book — but only when matchAddressBook is on (it is by default) and the stop carries neither latitude nor longitude. Send either coordinate and the name match never runs.
3. latitude and longitude — ready coordinates, geocoding skipped.
4. address — geocoded on the server.

A stop that reaches the end of that list with nothing to go on — no addressBookEntryId, no name match, no coordinates and no address — is refused with 400 invalid_argument, and that refusal fails the whole request, not just the one stop. A name-only stop is therefore safe exactly as far as the address book is: it resolves silently when the name is on file, and takes the entire call down with it when it is not.

An address the geocoder cannot resolve does not fail the request. The stop is saved with errorType: "GEOCODE_FAILED", listed in the response's geocodeFailedStops, and the solver routes everything else. If not a single address resolves, the plan lands in CREATED instead of DISPATCHING_IN_PROGRESS.

That tolerance belongs to POST /optimize and POST …/stops only. PUT …/stops/{stopId} geocodes strictly: a new address that will not resolve is 400 geocode_failed and the stop is left exactly as it was.

Request fields

Leaving driverIds unset is the most common way to get a plan that fails. The default is the whole team, and a single driver whose start point is in another city turns the entire plan DISPATCH_FAILED — read GET /team and choose deliberately, as Team, driver & analytics endpoints explains.

clientRequestId is what makes a retry after a timeout safe. Send the same id and you get the same plan back rather than a second one; Idempotent API requests covers what the replayed response does and does not reflect.

StopEntry

The same shape is used by POST /plans/{planId}/stops.

Plan and stop responses express arrival windows as timeWindows, with one exception: GET /address-book returns the legacy arrivalRangeFrom / arrivalRangeTo pair and no timeWindows at all. In the other direction, PUT …/stops/{stopId} has no arrivalRange* fields, so on that endpoint timeWindows is the only way to set a window.

Distribution strategies

The same four options as the Assign drivers & optimize dialog. Optimize routes explains when to pick which.

{
"name": "Friday deliveries", "date": "2026-09-05",
"routeStartTime": "08:30", "driverIds": [91, 93],
"clientRequestId": "crm-order-batch-4412",
"stops": [
  { "name": "Dr. Lee Clinic" },
  { "name": "Warehouse B", "address": "12 Main St, Brooklyn, NY",
    "timeWindows": [{ "from": "09:00", "to": "11:00" }],
    "serviceTime": 900,
    "email": "ops@warehouse-b.example", "phone": "+13475550142",
    "metadata": { "orderId": "A-118" } },
  { "name": "Pickup", "latitude": 40.7128, "longitude": -74.006,
    "assignedDriverId": 93 }
]
}

{
"planId": 315,
"status": "DISPATCHING_IN_PROGRESS",
"stopsCount": 3,
"createdAt": "2026-09-07T10:12:04Z",
"deduplicated": false,
"geocodeFailedStops": [],
"similarPlanIds": [311]
}

// status = "CREATED" when dispatch=false,
// or when no address resolved at all.
// similarPlanIds — plans with the same name and
// date: a hint that you may be making a duplicate.

The first stop in that request carries nothing but a name: it resolves through the address book. The second is geocoded from its address. The third supplies coordinates and pins itself to a driver.

geocodeFailedStops is the field to check on every response. It is empty on a clean run and holds the stops that were saved without usable coordinates otherwise — those stops exist in the plan, they are simply not on any route. They show up again in GET /plans/{planId} under unassignedSummary.byErrorType as GEOCODE_FAILED.

Errors: 400 validation_error, 400 invalid_argument, 400 invalid_time_windows, 400 invalid_driver_selection, 402 subscription_required, 403 insufficient_scope, 409 stop_limit_exceeded, 429 concurrent_optimization_limit, 429 too_many_requests. All four 429s in the API mean different things and want different retry strategies — branch on code, never on the status, as API limits & quotas sets out.

Plans across a date range, newest first.

{
"id": 315, "name": "Friday deliveries", "date": "2026-09-05", "status": "DISPATCHED",
"stopsCount": 3, "routesCount": 2, "createdAt": "…", "updatedAt": "…"
}

There is no pagination — only limit and a narrower date range. To export a long history, walk it day by day.

The plan's state and the optimization result: routes per driver, delivery progress, the next stop, failed and unassigned stops. This is the endpoint you poll after a 202 from /optimize or …/dispatch, until the status leaves DISPATCHING_IN_PROGRESS.

A cancelled plan is still returned here, with status: "CANCELLED" — it is not a 404.

{
"id": 315, "name": "Friday deliveries", "date": "2026-09-05", "routeStartTime": "08:30:00",
"status": "DISPATCHED", "hasUnoptimizedChanges": false,
"stopsCount": 3, "routesCount": 2, "totalTimeMinutes": 148, "totalDistanceMeters": 31240,
"createdAt": "…", "updatedAt": "…",
"routes": [ {
  "id": 802, "driverId": 91, "driverName": "Maya R.", "status": "IN_PROGRESS",
  "timezone": "America/New_York", "distance": 18400, "time": 92, "stopsCount": 2,
  "deliveredCount": 1, "failedCount": 0, "pendingCount": 1,
  "startedAt": "2026-09-05T12:31:00Z", "completedAt": null,
  "nextStop": { "id": 9012, "name": "Warehouse B", "position": 2,
                "expectedArrival": "2026-09-05T14:05:00Z", "expectedArrivalLocal": "10:05" },
  "startLocation": { "address": "…", "latitude": 40.73, "longitude": -73.95 }
} ],
"unassignedSummary": {
  "total": 1,
  "byErrorType": [ { "errorType": "GEOCODE_FAILED", "count": 1 } ],
  "preview": [ { "id": 9014, "name": "Ghost", "address": "asdfgh 99999", "errorType": "GEOCODE_FAILED" } ]
},
"failedStops": [ { "id": 9011, "name": "Dr. Lee Clinic", "routeId": 803, "driverName": "Danny L.",
                   "failureReason": "BUSINESS_CLOSED", "note": "closed till 2pm",
                   "statusChangedAtLocal": "09:42" } ]
}

// detailed adds routes[].stops[] in visit order and the full
// unassignedStops[]. Fields with no value are omitted.
// DISPATCH_FAILED adds "dispatchFailureReason".

routes is present only once optimization has produced something — in DISPATCHED, APPROVED, HAS_CHANGES and DISPATCH_FAILED. For a plan in CREATED, the stops are in unassignedStops and unassignedSummary instead.

failedStops are the stops a driver marked NOT_DELIVERED in the app, with their reason and the driver's note. statusChangedAtLocal and the other …Local fields are in the route's own timezone, which is the one to show a human; the plain fields are UTC.

Route fields

Stop fields in a response

Why a stop is unassigned

unassignedSummary.byErrorType counts the stops the optimizer could not place, by reason:

Soft-cancels the plan. The routes come down and drivers stop seeing it at once, but the plan, its stops and its proof-of-delivery photos are kept and the status becomes CANCELLED.

A plan that is still in DISPATCHING_IN_PROGRESS cannot be cancelled at all: the call is refused with 409 plan_state_transition and a message telling you to wait for DISPATCHED first. Cancelling is not a way out of an optimization that is taking too long.

{
"planId": 315, "name": "Friday deliveries",
"statusBeforeCancellation": "APPROVED", "cancelled": true,
"status": "CANCELLED", "restorable": true
}

Cancellation is refused once the day has started — any stop in DELIVERED or NOT_DELIVERED, or any route in IN_PROGRESS or COMPLETED — with 409 plan_cancellation_blocked, whose message names the numbers and points you at removing the remaining stops instead. A plan that is merely busy is a different refusal: 409 plan_state_transition, which means wait and retry. Plan lifecycle & statuses has both cases in full.

Errors: 404 plan_not_found, 409 plan_cancellation_blocked, 409 plan_state_transition, 403 insufficient_scope, 402 subscription_required.

Copies a plan onto another date: all the stops with all their settings, including the ones whose addresses never resolved, and none of the routes or delivery statuses. The copy comes back in CREATED — dispatch it when you are ready.

{ "date": "2026-09-06", "name": "Saturday (copy of Friday)" }

// name is optional — it defaults to the source plan's name

{
"id": 316, "name": "Saturday (copy of Friday)", "date": "2026-09-06",
"status": "CREATED", "stopsCount": 3, "routesCount": null,
"createdAt": "…", "updatedAt": "…"
}

This is the API side of Duplicate a plan. Because it needs only the write scope, it is the cheapest way for a read-and-write integration to set up tomorrow's work without ever holding the dispatch scope.