Inspection Support Network

Developer documentation / Route Builder

Route planning with an AI assistant or the API

ISN’s Route Builder decides which inspector takes which order, and when. The same planner is open to an AI assistant connected through the MCP server and to your own integration through the ISN API: read a day’s routes, ask for a plan for one day or a whole week, and send it to a person for approval. Nothing an assistant or an integration proposes reaches the calendar until someone approves it.

How it works

  1. Read. See a day as the Route Builder page shows it — each inspector’s stops in order with drive times, and the orders nobody has yet — or ask why a particular inspector cannot take an order.

  2. Suggest. Ask for a plan for one day, a range of up to seven days (“plan next week”) or chosen dates. ISN plans the unassigned orders around every booked appointment and around any draft a scheduler has saved, and moves neither. It writes nothing and returns a plan_id, valid for 30 minutes.

  3. Submit. Show the plan to the user, then submit the plan_id. It lands in each day’s saved draft as suggestions. Still nothing is on the calendar.

  4. Approve. A scheduler opens the day in Route Builder, sees “AI plan waiting for approval”, and accepts or rejects each suggestion before applying — or an integration calls approve or reject (see Approval). Applying is the approval.

  5. Follow up. Check whether the plan was approved, applied or rejected, and undo an apply within 15 minutes.

Turning it on

Reading routes and asking for suggestions works for anyone who can use the Route Builder. Submitting a plan for approval is off until an owner turns it on for the office: in Route Builder, open Settings and switch on Let AI assistants submit route plans for approval, or call PUT /route-builder/settings/ai-plans. Each change is logged with who made it. Turning it off stops new submissions; a plan already waiting stays for a person to decide.

Who can read and suggest
Owners, and office admins with calendar access — the same people who can open the Route Builder page.
Who can submit, approve and undo
Those who can also apply routes on the page: owners, or office admins with Edit Inspections. The person who asked for a plan may approve it on the page.
Offices
Every call takes an optional office_id and otherwise works in the user’s own office. Another office must be one the user can switch to in ISN; an order or inspector from another office is “not found”.

What a plan will never do

Move a booking you did not name
Booked appointments are planned around. A plan moves one only when you name it in order_ids, and then only to another inspector at the same time, or to a new time that day if an owner has allowed it in Route Builder settings. Never to another day. Each such row carries moved_from, and rejecting it puts the booking back where it was.
Override a scheduler
Orders a scheduler has placed in a saved draft are planned around, never moved. A second plan for the same day waits until the first has been decided; once it is, the next submit takes its place on the draft and says so in its response (replaced, with the earlier plan’s id and submission time).
Change an order’s date
When you plan days without naming orders, each order is planned on its own date. An order moves to another day only if you name it in order_ids (a backlog order).
Apply a stale plan
Submitting is refused, with nothing written, if an affected inspector’s day, a planned order or the saved draft changed since the suggestion, or the day is locked. Suggest again.
Take inspectors and times from you
No call accepts an inspector and a time to write. The only writes are a plan ISN proposed, a person’s decision on it, and undo.

MCP tools

On the ISN MCP server at https://inspectionsupport.com/{companyKey}/mcp, alongside the other tools. Orders and inspectors are UUIDs, days are YYYY-MM-DD, times are HH:MM in the office’s time zone. Read tools run without a prompt; submit and undo always ask the user first.

ToolWhat it doesAsk forAccess
get_route_builder_officesThe offices the user may plan, and which is their own.“Which offices can I plan?”read
get_route_builder_dayOne day: each inspector’s stops in order (arrive, depart, address, drive minutes from the previous stop — null when not yet known, never zero), the unassigned orders, and whether a scheduler saved a draft.“What does Tuesday look like?”read
get_route_builder_orderOne order’s planning facts and anything missing before it can be planned (no date, no services, no geocode…).“Why won’t this order plan?”read
get_route_builder_order_fitFor one order on one day, whether each inspector could take it and, if not, why — in the Route Builder page’s words, with the hours involved.“Why can’t Jane take 1234 Elm on Tuesday?”read
get_route_builder_historyRecent applies: who, when, how many orders, whether undone, and whether it was an AI plan and who asked for it.“What was applied this week?”read
get_route_builder_suggestionA plan for one of day, start_date+end_date or days (up to 7). Optional order_ids (up to 50), inspector_ids, respect_capacity. Returns what it placed per day, what it could not place with the reasons, and a plan_id. Writes nothing.“Plan Tuesday”, “plan next week”, “fit these three in this week”read
submit_route_builder_planPuts a plan (or chosen orders from it) into each day’s draft for approval, with an optional note for the approver.“Send that plan for approval”write
get_route_builder_plan_statusPer day: still waiting, applied (approved) or dismissed (rejected), with any reason given.“Was my plan approved?”read
undo_route_builder_applyPuts every order from one apply back, within 15 minutes, all or nothing.“Undo that”write

There is no approve tool. An assistant can propose a plan; only a person, on the Route Builder page or through an integration other than the one that submitted it, can approve it. To find orders waiting for an inspector on other days, use search_orders with unassigned_only and a date range.

Things to ask

Questions that work as written, once ISN is connected to your assistant. Name orders by address or client and days by date or weekday; the assistant looks up the ids. Dates are in the office’s time zone.

See a day
“What does next Tuesday look like for the inspectors?”
“Show me Friday’s routes and anything still unassigned.”
“How much driving does Maria have on the 24th?”
One order
“Why isn’t 1234 Elm Street planned yet?”
“Who could take the Johnson inspection on Thursday, and why not the others?”
“Can Dan fit 88 Harbor Road in on Monday?”
Plan
“Plan Tuesday’s unassigned orders.”
“Plan next week, Monday to Friday.”
“Fit these three backlog orders in somewhere this week: 1234 Elm, 88 Harbor Road and the Johnson job.”
“Plan Wednesday with only Maria and Dan.”
“Plan Thursday and ignore the daily capacity.”
“Would it be better if someone else took 1234 Elm on Tuesday?” (a booked order you name may move to another inspector at its booked time)
Send for approval
“That looks good, send it for approval.”
“Send just Maria’s stops for approval, with a note that the Elm Street client asked for the morning.”
Follow up
“Was my plan for Tuesday approved?”
“Why was Thursday’s plan rejected?”
“What was applied to the calendar this week, and by whom?”
“Undo that last apply.” (within 15 minutes of the apply)
Find work to plan
“Which orders in the next two weeks have no inspector yet?”
“Which offices can I plan?”

What will not work: asking the assistant to approve a plan (a person does that on the Route Builder page), to put a specific inspector on an order at a specific time (no tool writes that), to move a booking to another day, or to plan more than seven days at once.

Endpoints in the ISN API

The same operations for integrations, under https://inspectionsupport.com/{companyKey}/rest/route-builder, signed in as for every other ISN API call. Each answers with the matching MCP tool’s result, wrapped as {"status": "ok", "result": {…}}; a refusal is {"status": "error", "message": "…"} with 400 (bad input, or the day or plan changed), 403 (not permitted, or AI plans are off) or 404 (not found, expired, or nothing waiting). Request bodies are JSON; an empty body is allowed wherever nothing is required.

CallWhat it does
GET /route-builder/officesOffices you may plan.
GET /route-builder/days/{day}One day’s routes, unassigned orders and draft. Optional inspector_ids, comma-separated.
GET /route-builder/orders/{order_id}One order’s planning facts.
GET /route-builder/orders/{order_id}/fit?day=Which inspectors could take it, and why not the rest.
GET /route-builder/historyRecent applies. Optional day, limit.
POST /route-builder/suggestionsA plan, as get_route_builder_suggestion. Writes nothing; returns plan_id.
POST /route-builder/plans/{plan_id}/submitSubmit for approval. Optional order_ids, note.
GET /route-builder/plans/{plan_id}Waiting, applied or dismissed, per day, with any rejection reason.
POST /route-builder/days/{day}/approveApply the day’s waiting suggestions (all, or order_ids). See Approval.
POST /route-builder/days/{day}/rejectRemove them. Optional order_ids, and a reason the assistant can read.
POST /route-builder/applies/{apply_id}/undoUndo within 15 minutes.
GET / PUT /route-builder/settings/ai-plansRead, or (owners) change, whether the office accepts AI plans: {"enabled": true}.

Every call, with its parameters and a sample request and response for each, is in the API reference under Route Builder, where you can also try it against your own company key.

Approval

On the Route Builder page, the plan shows as suggestions on each inspector’s lane, drawn on the map and checked for clashes like any other change. The scheduler accepts or rejects each one and applies; the page will not apply while any are undecided.

Through the API, approve does what accepting and applying does. Because the caller cannot see the board, it also refuses, writing nothing, when:

Same caller
The plan was submitted by the same API client (for the ISN API, the same user). A plan must be approved by someone or something other than what asked for it, so an integration cannot plan and approve on its own.
Order changed
A planned order was assigned or cancelled after the plan was submitted.
Clash
An inspector now has an appointment that overlaps a suggested stop, for example one booked by phone after the plan was made.
Locked or busy
The inspector’s day is locked, or another apply for the day is running.

Every apply of an AI plan is recorded in Route Builder history with the person who approved it and the person who asked for it.

What customers hear

Automatic emails and texts
The office’s own scheduled emails and texts (reminders before the inspection, and so on) follow the new date and time, as they do for any change.
Reschedule notice
For each approved order whose date or time changed, ISN sends the reschedule notice the approving user has switched on in their reschedule settings — to the client, agents, inspector and so on, as they chose. Nothing is sent if they have none switched on.
When
16 minutes after the apply, once the undo window has closed, and only for orders still exactly as the plan left them. An undone apply sends nothing.

Limits

Days
Up to 7 per suggestion.
Orders
Up to 50 named orders per suggestion, and up to 50 planned per day.
Plan
A plan_id lasts 30 minutes and can be submitted once, by the user who asked for it, in the same office.
Undo
15 minutes after an apply, and all or nothing: if anyone has changed one of those orders since, nothing is reverted.
Capacity
Each inspector’s daily capacity is respected unless you pass respect_capacity: false. A week’s plan does not balance an inspector’s load across days.
Speed
A day whose drive times ISN has not worked out before can take several seconds; a week, longer.