Visits

Create a visit

POST /v1/journeys with:

Field
customer.name	required	Shown nowhere publicly; for your team and messages.
customer.email, customer.phone	optional	Where messages go. With our emails, a visit without an email is skipped (you can still send the link yourself).
destination	required	lat + lng, or a uprn, or both, plus an optional label shown to the customer.
externalRef	optional	Your job or visit reference, up to 100 characters. Filter by it later.
operativeId	optional	One of your operatives. Wins over operative.
operative.displayName	optional	A provisional name, for example from a CSV, before you know who's going.
appointment	optional	{ start, end? }, shown to the customer until the operative sets off.
visitDate	optional	YYYY-MM-DD; defaults to the appointment's day, or today. Decides the dispatch board day.
notify	default true	Send the booked message straight away.

The response is 201 with { journey, live }. Each visit counts towards the monthly allowance unless it's cancelled before setting off. When the allowance is used up you get 402 allowance_exhausted.

Create many at once

POST /v1/journeys/bulk with { "journeys": [ … ] } takes up to 200 visits, each shaped as above. The response is 207 with one result per input, in order:

[
  { "index": 0, "ok": true, "journey": { "id": "jrn_…" } },
  { "index": 1, "ok": false, "error": { "code": "uprn_not_found", "message": "…" } }
]

Each visit succeeds or fails on its own, so retry only the failures.

Find visits

• GET /v1/journeys?status=en_route&limit=50: newest first. Statuses are scheduled, en_route, arrived, cancelled and expired.
• GET /v1/journeys?externalRef=JOB-1001: by your own reference.
• GET /v1/journeys/{id}: one visit, with live (the current tracking state) while its live data exists.
• GET /v1/journeys/{id}/history: the position trail and the ETAs shown, on plans with visit history (402 feature_not_in_plan otherwise).

Running late

POST /v1/journeys/{id}/delay with { "reason": "traffic", "minutes": 30 } before or during the journey.

• Reasons: traffic, roadworks, parking, previous_job or stopped.
• What happens: the tracking page shows the new time, the customer gets the journey.delayed message, and the snapshot's delay holds the reason and arriveBy.

Change and cancel

• Assign or reorder visits through the dispatch board.
• POST /v1/journeys/{id}/cancel tells the customer, and the tracking page shows the visit as cancelled.