---
key: configure-daily-route-arrangements
title: Configure daily route arrangements through the API
audience: developer
section: api/getting-started
routes: []
permissions: [schedule.view]
since: 0.0.1
updated: 0.0.1
status: published
summary: Set explicit start and finish choices, private bases and daily overrides without changing appointments.
keywords: [routes, technician, shop, starting location, private base, departure, inheritance]
related: [api-record-identity, api-errors, find-what-to-call]
---

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:

| Layer | Path below `/route-settings` | Write permission |
|---|---|---|
| Organization | `/organization` | `schedule.settings.write` or `org.settings.write` |
| Operating branch | `/branches/{branch_uid}` | The organization settings permissions |
| Technician | `/technicians/{resource_uid}` | `schedule.resources.update` |
| Working day | `/technicians/{resource_uid}/days/{YYYY-MM-DD}` | `schedule.edit` |

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.

```json
{
  "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.