Configure daily route arrangements through the API

Set explicit start and finish choices, private bases and daily overrides without changing appointments.

Use /v1/schedule/route-settings to configure a technician's route arrangements. These operations change route settings, not appointment times. Discover their current permission requirements in the operations index.

Read and replace a layer

GET and PUT use the same path:

A GET returns uid, scope, settings and version. An absent override has uid: null, settings: null and version: 0. A PUT replaces that layer and must include both expected_uid and expected_version from the GET. Send settings: null to clear the override and inherit again. A stale write returns 409, including when an override was deleted and recreated after the read.

{
  "expected_uid": null,
  "expected_version": 0,
  "settings": {
    "start": {"kind": "branch", "branch_uid": "branch_a1b2c3d4e5f6a1b2"},
    "finish": {"kind": "return_to_start"},
    "earliest_departure": "08:00:00",
    "latest_finish": "17:00:00",
    "travel_allowance_seconds": 300,
    "traffic": "static",
    "paid_travel": "between_visits"
  }
}

Each non-null field overrides its inherited value. A start or finish choice is one whole location; its fields are never combined with a different location. Hours are local to the working day's scheduling timezone. Payroll choices (between_visits, all_route, none) are separate from route feasibility.

Read the effective arrangement

GET /technicians/{resource_uid}/effective?day=YYYY-MM-DD returns all four layers, effective values, each value's source, resolved start and finish and ready. The branch layer belongs to the technician's operating branch; changing the selected branch does not replace it.

Unconfigured or unavailable endpoints produce ready: false. Nova does not copy a profile address or silently exclude a commute. Explicit first_job and last_job choices report which driving is excluded. Branch coordinates must be available. A deleted private base leaves a missing-setting state.

Save a private base

GET or POST /technicians/{resource_uid}/bases. POST accepts a label, optional address and a complete, confirmed latitude/longitude pair. Updates and deletion use /bases/{base_uid} with the current expected_version (a body field for PUT, a query parameter for DELETE). Coordinates must be finite and in range; zero is valid.

Use {"kind":"private_base","base_uid":"rbase_..."} only in that technician's settings or daily override. Organization and branch layers cannot refer to someone's private base. A day's custom endpoint requires a label and coordinates; ordinary defaults use a branch or saved base.

The technician can read their own private bases. Saving or deleting a base needs schedule.resources.update and branch access. Managing another person's saved addresses also needs that permission. An authorized dispatcher can resolve the effective endpoint needed to inspect the route; another schedule viewer cannot. Audit records contain opaque references and versions, without private addresses or coordinates.

Use a current position deliberately

An own-technician day override can select kind: "custom" with a label, finite latitude/longitude, position_captured_at and position_accuracy_meters. This is available only for today in the technician's effective scheduling timezone. Capture must be recent, not in the future, with positive accuracy no worse than 1,000 metres. The server independently validates those fields. Another person's position cannot be submitted as their current location.

Both clients request foreground location only after a deliberate button tap, show the captured pin for review and save it through the conditional day-setting write. There is no background tracking or guessed home location. If capture is unavailable, choose an explicitly confirmed custom pin instead. Native users can edit today's or another selected day's start/finish override and return to inherited defaults; normal organization/branch/technician layers are managed in the web arrangement editor.