Skip to main content
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. The target audience of this briefing checklist is whoever knows the operation: an operations manager, a dispatcher, the person who owns the data export.
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 Three kinds of break 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?
The API doesn’t geocode addresses — every position submitted must already be a real {lat, lon} pair. If you can’t geocode your addresses yourself, contact customer.success@kardinal.ai: the team can geocode an address set for you on request. 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: