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
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.
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.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.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
approveorreject(see Approval). Applying is the approval.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_idand 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 carriesmoved_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.
| Tool | What it does | Ask for | Access |
|---|---|---|---|
get_route_builder_offices | The offices the user may plan, and which is their own. | “Which offices can I plan?” | read |
get_route_builder_day | One 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_order | One 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_fit | For 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_history | Recent 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_suggestion | A 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_plan | Puts 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_status | Per day: still waiting, applied (approved) or dismissed (rejected), with any reason given. | “Was my plan approved?” | read |
undo_route_builder_apply | Puts 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.
| Call | What it does |
|---|---|
GET /route-builder/offices | Offices 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/history | Recent applies. Optional day, limit. |
POST /route-builder/suggestions | A plan, as get_route_builder_suggestion. Writes nothing; returns plan_id. |
POST /route-builder/plans/{plan_id}/submit | Submit 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}/approve | Apply the day’s waiting suggestions (all, or order_ids). See Approval. |
POST /route-builder/days/{day}/reject | Remove them. Optional order_ids, and a reason the assistant can read. |
POST /route-builder/applies/{apply_id}/undo | Undo within 15 minutes. |
GET / PUT /route-builder/settings/ai-plans | Read, 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_idlasts 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.