This page is optional — nothing in the API requires it. Its purpose is to hand whoever builds the integration, a human or an AI agent, the business context a raw data export can’t contain on its own: is a time window really a hard cutoff, or just a preference? Can a vehicle reload at the depot mid-day? What’s the real capacity of a delivery van? Answering these once, wherever you keep notes, means that context is available when the plan gets modeled, instead of being silently guessed at deep inside a payload.
If you do go through it, work through the questions with whoever knows the operation — an operations manager, a dispatcher, the person who owns the data export — and record each answer in your own copy (a doc, a ticket, a spreadsheet). Leave a question open if the answer is genuinely unknown rather than inventing one to move on.
Building a payload from a client’s raw data? Pair this checklist with Start here if you’re an AI agent — the answers here are exactly the inputs that let that checklist resolve open questions instead of guessing at them.
1. Context
- Operation / business name
- Sector
- Country / region of operations
- Problem to solve / goal of this integration
2. Scope
- Which depots or sites should be in scope? (name, address, coordinates)
- Any depots present in the data but explicitly out of scope?
- Which vehicles / fleets should be in scope?
- What period does the data cover, and what period should the plan use?
- How many vehicles/drivers run per depot per day, roughly? (sanity-check figure)
3. Data you’re working from
- What files are you working from, and what does one row represent?
- Is there a grouping key that turns several rows into a single delivery stop (for example, depot + date + tour + customer)?
- Are there rows that are not real deliveries and should be excluded (returns, internal transfers, cancelled orders)?
- Any column you know is unreliable or shouldn’t be trusted at face value?
- Any known data-quality issues (corrupted addresses, internal codes instead of real addresses, inconsistent units, encoding/whitespace issues)?
- What unit is weight/volume/quantity expressed in?
The row-to-stop aggregation key and the “don’t trust this column” list are two of the most common silent-error sources when modeling from a raw export — get them directly from someone who knows the operation rather than inferring them from the file.
4. Fleet and vehicles
- Is the fleet homogeneous (all vehicles identical), or are there several vehicle types?
- What is the real capacity of each vehicle type (weight / volume / pallet or container count — the actual nameplate figure)?
- Should vehicle capacity be modeled as a hard constraint at all, or is it never actually the bottleneck?
- Are any vehicles specialized (refrigerated, hazmat, bicycle/light vehicle, tail-lift required, etc.)?
- Does a vehicle depart from and return to a fixed depot, or can a route start/end elsewhere?
- Is the fleet size fixed (given), or should the plan size the fleet itself — that is, is “fewer vehicles” a valid outcome?
Real fleet size/composition and real vehicle capacity are almost never recoverable from a raw export alone — expect to flag at least one of these as an open question.
5. Working hours and breaks
- What time do drivers leave the depot, and what time do they return?
- Is there a maximum working duration per day, independent of that window?
- Are breaks mandatory?
- If so: a fixed clock-time window, or triggered by cumulative driving/working time?
- Break duration?
Break rules are very often collective-bargaining-agreement or labor-code facts specific to the sector/country — no generic default can supply the real figure. See Data model for how breaks[] represents each trigger type.
6. Delivery stops
- How long does a typical stop take (service/unload time)? Is it flat, or does it scale with order size (for example, number of lines/pallets)?
- Do customers have delivery time windows?
- If a vehicle arrives outside the window: is the delivery refused/impossible (hard constraint), or just late/undesirable (soft preference)?
- Are there special access constraints at some stops (site closes at a fixed hour, specific equipment or skill required, appointment-only access)?
Hard vs. soft time windows is the single most frequently recurring ambiguity when modeling a real operation — a stated business hour is not automatically proof of a hard cutoff. See Hard vs soft constraints.
7. Depot and multi-trip operations
- Can a vehicle return to the depot mid-day to reload and go out again, or is it strictly one loop per vehicle per day?
- If reloads happen: how long does loading/unloading at the depot take per visit?
- Is there a limit on how many vehicles can be at the depot/dock at the same time?
A single loop per vehicle per day isn’t the only valid pattern — many real operations reload at the depot mid-shift, and modeling that as a single loop silently drops the stops that don’t fit. See Multi-trip tours if reloads apply to this operation.
8. Geocoding and addresses
- Are addresses generally clean and precise, or are there known problem categories (internal codes, rural/no-formal-address locations, motorway points, generic street names shared across villages)?
- If a stop can’t be geocoded precisely: is an approximate location (for example, postal-code centroid) acceptable, or should the stop be excluded instead?
- Preferred geocoding provider / country code, if there’s an existing preference or account?
Kardinal doesn’t geocode addresses — every position submitted must already be a real {lat, lon} pair. If precise coordinates aren’t available for some stops, that’s a data-quality gap to flag, not something to paper over with a placeholder. See §5 of the AI agent checklist.
9. Other technical facts
- Timezone of operations
- Currency
- Is traffic-aware routing relevant / available on the account?
- Any custom KPI already tracked today (for example, CO2, service level) that the plan should also report?
- Any account/agency scoping detail (for example, one plan across all depots versus one per depot)?
See also
Once these questions are answered, that record becomes the reference to check your payload against as you model it:
