SchedAI Input Specs

SchedAI Service Input Specs

SchedAI Service uses a multi-file routing bundle: technicians, locations, visits, and a required travel-time matrix, with an optional travel-distance matrix for distance reporting.

Back to Input Specs Resources Hub

Overview

Use this guide to prepare valid input files for this workspace. Review the required files, exact column names, example rows, and common formatting rules before uploading.

Required files

Optional files

Spec sections

Upload section

Service Upload Bundle

Upload the full service bundle together so depot references, visit references, and travel-matrix rows all resolve against the same location set.

Required file

technicians.csv

One row per technician.

Requirements

Required columns

tech_id
start_depot_id
shift_windows

Optional columns

display_name
skills
end_depot_id
max_duty_minutes
max_overtime_minutes
fairness_eligible
preferred_visit_ids
blocked_visit_ids

Reference requirements

start_depot_id and end_depot_id must match depot rows in locations.csv.

Format limitations

shift_windows accepts date:HH:MM-HH:MM or date:HH:MM AM/PM-HH:MM AM/PM segments separated by | or ;; integer minute values are also accepted for backward compatibility.

Unsupported currently

Day-only overnight technician windows are blocked — use an ISO date qualifier such as 2026-05-04:10:00 PM-6:00 AM for overnight routes.
Full multi-day routing is not supported in this version.
Technician windows spanning more than one midnight are not supported.

Value rules and examples

shift_windows accepts HH:MM or AM/PM values inside date:start-end or day:start-end pairs, joined with | or ;, for example 2026-05-04:10:00 PM-6:00 AM or mon:08:00-17:00.
Integer minute values are also accepted for backward compatibility.
Same-day technician windows may use a weekday or ISO date as the qualifier, for example mon:08:00-17:00 or 2026-05-04:08:00-17:00.
Dated one-midnight overnight technician windows are supported, for example 2026-05-04:10:00 PM-6:00 AM.
Day-only overnight technician windows are blocked — provide an ISO date qualifier for any window that crosses midnight.
start_depot_id and end_depot_id must match depot rows in locations.csv.
fairness_eligible accepts true/false, yes/no, y/n, or 1/0.

Example CSV table

tech_id	display_name	skills	start_depot_id	end_depot_id	shift_windows	max_duty_minutes	max_overtime_minutes	fairness_eligible	preferred_visit_ids	blocked_visit_ids
T1	Avery	hvac;install	DEPOT-A	DEPOT-A	2026-05-04:10:00 PM-6:00 AM	540	30	true

Required file

locations.csv

All depots and customer locations referenced elsewhere in the service scenario.

Requirements

Required columns

location_id
label
kind

Optional columns

lat
lng

Reference requirements

location_id values are referenced by technicians.csv, visits.csv, and travel matrix files.

Format limitations

kind must be depot or customer.

Value rules and examples

Use kind=depot for depot rows and kind=customer for service locations.
location_id values must stay unique.
Technician depot references and visit location_id values must match this file.
lat and lng are optional in the frontend draft, but provide them when you want geography-aware reporting.

Example CSV table

location_id	label	kind	lat	lng
DEPOT-A	North Depot	depot	43.700	-79.420
SITE-1	Harbor Clinic	customer	43.690	-79.410

Required file

visits.csv

One row per visit or service stop.

Requirements

Required columns

visit_id
location_id
day
earliest_start_minute
latest_start_minute
service_duration_minutes

Optional columns

customer_id
required_skills
priority
mandatory
preferred_tech_ids
disallowed_tech_ids
pair_penalty_by_tech
max_tardiness_minutes

Reference requirements

location_id must match a customer row in locations.csv; preferred/disallowed tech ids must match technicians.csv.

Format limitations

earliest_start_minute and latest_start_minute accept HH:MM or AM/PM values; integer minute values are also accepted for backward compatibility; list fields use | or ;.

Unsupported currently

Visit windows that cross midnight are not supported — latest_start_minute must be on or after earliest_start_minute on the same date.
Use the actual next-day ISO date in the day column for after-midnight visits inside an overnight technician route.

Value rules and examples

earliest_start_minute and latest_start_minute accept HH:MM or AM/PM values, for example 10:30 PM or 08:00; integer minute values are also accepted for backward compatibility.
latest_start_minute must be on or after earliest_start_minute on the same ISO date.
For after-midnight visits inside an overnight technician route, use the actual next-day ISO date in the day column with a same-day window, for example day=2026-05-05, earliest_start_minute=1:00 AM, latest_start_minute=2:00 AM.
location_id must match a customer row in locations.csv, not a depot row.
required_skills, preferred_tech_ids, and disallowed_tech_ids use | or ; separators.

Example CSV table

visit_id	customer_id	location_id	day	earliest_start_minute	latest_start_minute	service_duration_minutes	required_skills	priority	mandatory	preferred_tech_ids	disallowed_tech_ids	pair_penalty_by_tech	max_tardiness_minutes
V1	CUST-1	SITE-1	2026-05-04	10:30 PM	11:30 PM	30	hvac	90	true				10
V2	CUST-2	SITE-2	2026-05-05	1:00 AM	2:00 AM	30	hvac	90	true				10

Required file

travel-times.csv

Row-form travel-time matrix.

Requirements

Required columns

from_location_id
to_location_id
travel_time_minutes

Optional columns

No optional columns documented for this file.

Shape requirements

travel-times.csv must cover every uploaded location pair, including diagonal rows.

Reference requirements

from_location_id and to_location_id must match location_id values from locations.csv.

Value rules and examples

Cover every location pair, including depot-to-customer, customer-to-customer, and diagonal rows.
Diagonal travel_time_minutes values should be 0.
Values must be finite and non-negative.

Example CSV table

from_location_id	to_location_id	travel_time_minutes
DEPOT-A	DEPOT-A	0
DEPOT-A	SITE-1	18

Optional file

travel-distances.csv

Optional row-form distance matrix for distance reporting.

Requirements

Required columns

from_location_id
to_location_id
travel_distance_km

Optional columns

No optional columns documented for this file.

Shape requirements

travel-distances.csv must cover the same uploaded location pairs when provided.

Reference requirements

from_location_id and to_location_id must match location_id values from locations.csv.

Value rules and examples

Use the same location pairs and ordering strategy as travel-times.csv.
Diagonal travel_distance_km values should be 0.
Values must be finite and non-negative.

Example CSV table

from_location_id	to_location_id	travel_distance_km
DEPOT-A	DEPOT-A	0
DEPOT-A	SITE-1	11.2

Common mistakes

Uploading locations without depot rows, then referencing those missing depots from technicians.csv.
Using incomplete travel-matrix pairs so one or more locations are missing from the matrix.
Providing latest_start_minute earlier than earliest_start_minute on visits.csv.

Quick rules

Every technician depot id must match a depot row in locations.csv.
Every visit location_id must match a row in locations.csv.
HH:MM and AM/PM times are accepted in shift_windows; dated one-midnight overnight technician windows are supported. Day-only overnight windows are blocked.
For after-midnight visits inside an overnight route, use the actual next-day ISO date in the visit day column — visit windows that cross midnight are not supported.
travel-times.csv must be square across every uploaded location and should use 0 on the diagonal.

Navigate

Keep the right guide close by

Pair this upload guide with the product page for workflow context or the resources hub for related public material.

Input Specs index Resources hub

Navigate

Keep the right input guide close

Return to the input-spec library for another upload contract, or go back to the resource hub for quickstarts, how-to guides, and use cases.

Back to Input Specs Back to Resources