API and Data Types Reference

API endpoints

All scheduler routes are mounted under /api/scheduler and require the scheduler workspace bundle plus authenticated access. My Day Run is the exception — available to any authenticated user.

Method	Path	Purpose
GET	`/api/scheduler/overview`	Full scheduler state: jobs, engineers, stats, insights
GET	`/api/scheduler/engineers`	Current eligible field-resource summaries
GET	`/api/scheduler/my-day-run`	Personal day-run for the authenticated user
GET	`/api/scheduler/day-run`	Preview a day run
POST	`/api/scheduler/day-run/apply`	Apply a reviewed day run
POST	`/api/scheduler/suggest-slots`	Rank slots for one job
POST	`/api/scheduler/propose-slots`	Preview ranked slots for a selected batch
POST	`/api/scheduler/replan-day`	Preview a redistribute-or-shift day plan
POST/PATCH	`/api/scheduler/tasks`, `/api/scheduler/tasks/:id`	Create or update a planner task
POST	`/api/scheduler/bulk-update/preview`, `/api/scheduler/bulk-update`	Preview and apply up to 100 job updates
POST	`/api/scheduler/history/:id/undo`	Undo a scheduler change
POST	`/api/scheduler/bulk-create-inspections`	Batch create up to 50 inspections
POST	`/api/scheduler/deploy/preview`, `/api/scheduler/deploy/apply`	Preview and deploy a batch
GET	`/api/scheduler/ppm-forecast`	12-month Scheduler Forecast for inspections, work orders, and planner tasks
GET/POST	`/api/scheduler/arrival-windows`	List or create arrival windows
PATCH/DELETE	`/api/scheduler/arrival-windows/:id`	Update or archive an arrival window
GET/POST	`/api/scheduler/customer-notifications`	Read or record appointment notifications
GET/POST	`/api/scheduler/buckets`	List or create capacity buckets
PATCH/DELETE	`/api/scheduler/buckets/:id`	Update or archive a capacity bucket
POST	`/api/scheduler/routine-engine/preview`, `/api/scheduler/routine-engine/apply`	Preview and generate routine draft work
POST	`/api/scheduler/recurring-import/preview`, `/api/scheduler/recurring-import/apply`	Preview and apply recurring CSV work

Overview response shape

GET /api/scheduler/overview returns the complete scheduler state. All filter parameters are passed as query strings.

{
  jobs: SchedulerJob[],
  engineers: EngineerSummary[],
  filters: {
    start, end, engineerId, siteId, jobType, status, q,
    postcodeArea, region, equipment, ooh
  },
  stats: {
    totalJobs, scheduledJobs, unassignedJobs, overdueJobs,
    scheduledHours, conflictCount, unscheduledJobs,
    jobsWithWarnings, jobsWithBlockingWarnings, draftJobs,
    readyToDeployJobs, deployedTodayJobs, routeSuggestionCount,
    capacitySummary: {
      overloadedEngineers, availableEngineers,
      assignedHours, flaggedAssignments
    },
    warningBuckets: {
      blocked, flagged, unassigned, unscheduled,
      draft, ready, deployed, awaiting, acknowledged
    },
    actionCounts: {
      needsAssignment, needsScheduling, dueSoon,
      overloadedEngineers, readyToDeploy, draftJobs
    }
  },
  insights: {
    routeSuggestions: SchedulerRouteSuggestion[],
    recentChanges: SchedulerHistoryItem[],
    recentDeploymentBatches: DeploymentBatch[],
    selectionHints: { preferredAction, focusLabel }
  }
}

SchedulerJob type

The unified job object representing inspections, work orders, and planner tasks within the scheduler.

Field	Type	Description
`key`	string	Unique key: `"entityType:id"`
`id`	string	Entity ID
`entityType`	`"inspection"` \| `"work_order"` \| `"task"`	Source entity type
`jobType`	string	Specific type (e.g. `annual`, `remedial`, `survey`)
`title`	string	Display title
`subtitle`	string \| null	Secondary display text
`status`	string	Current status
`priority`	string \| null	`low`, `normal`, `high`, `urgent`
`scheduledDate`	string \| null	ISO datetime for exact scheduling
`targetMonth`	string \| null	`YYYY-MM` for month-level planning
`bookingStatus`	string	`provisional`, `date_offered`, `confirmed`, or `do_not_move`
`deploymentState`	`"draft"` \| `"deployed"`	Current deployment state
`deployedAt`	string \| null	ISO datetime of last deployment
`deployReady`	boolean	Whether the job can be deployed
`engineerAcknowledgedAt`	string \| null	ISO datetime when the engineer acknowledged the deployed work (via opening their day run). `null` if not yet acknowledged or not deployed.
`engineerVisibleFrom` / `engineerVisibleUntil`	string \| null	Optional field-visibility window
`deployBlockedReasons`	string[]	Reasons blocking deployment
`estimatedDurationMinutes`	number	Estimated work duration
`scheduleWindowStart`	string \| null	Earliest acceptable date
`scheduleWindowEnd`	string \| null	Latest acceptable date
`scheduleFlexDays`	number \| null	Acceptable flex around scheduled date (0-120)
`siteId`	string \| null	Associated site
`siteName`	string \| null	Site display name
`systemId`	string \| null	Associated system
`systemName`	string \| null	System display name
`city`	string \| null	Site city
`postcode`	string \| null	Site postcode
`postcodeArea`	string \| null	Extracted area code (e.g. `SW` from `SW1A 1AA`)
`latitude`	string \| null	Site latitude
`longitude`	string \| null	Site longitude
`engineerIds`	string[]	Assigned engineer IDs
`engineerNames`	string[]	Assigned engineer display names
`requiredCompetencies`	string[]	Computed competency requirements
`crewSizeRequired`	number	Number of crew required (default 1)
`accessEquipment`	string[]	Normalised equipment values
`outOfHours`	boolean	Out-of-hours flag
`siteAccessNotes`	string \| null	Combined site access notes
`siteSchedulingRules`	object \| null	Site-level scheduling constraints
`bucketId` / `bucketName`	string \| null	Optional capacity bucket assignment
`arrivalWindowId` / `arrivalWindowLabel`	string \| null	Applied reusable customer arrival window
`arrivalWindowManual`	boolean	Whether the arrival window was chosen explicitly instead of matched automatically
`validationWarnings`	SchedulerWarning[]	Current warnings
`detailHref`	string \| null	Link to the entity detail page

BulkUpdatePatch type

Sent to POST /api/scheduler/bulk-update. All fields are optional — only included fields are applied.

Field	Type	Constraints
`engineerIds`	string[] \| null	Keep, clear, or set valid org members with `canBeScheduled` according to assignment mode
`scheduledDate`	string \| null	ISO datetime; mutually exclusive with `targetMonth`
`targetMonth`	string \| null	`YYYY-MM`; mutually exclusive with `scheduledDate`
`estimatedDurationMinutes`	number \| null	15-1440
`priority`	string	`low`, `normal`, `high`, `urgent`
`status`	string \| null	`pending`, `in_progress`, `completed`, `cancelled`
`bookingStatus`	string \| null	`provisional`, `date_offered`, `confirmed`, or `do_not_move`
`engineerVisibleFrom` / `engineerVisibleUntil`	string \| null	Optional engineer visibility window
`arrivalWindowId`	string \| null	Workspace arrival window or manual override
`scheduleWindowStart`	string \| null	ISO datetime
`scheduleWindowEnd`	string \| null	ISO datetime
`scheduleFlexDays`	number \| null	0-120
`crewSizeRequired`	number \| null	1-50
`accessEquipment`	string[] \| null	Validated against VALID_EQUIPMENT enum
`outOfHours`	boolean	—

EngineerSummary type

Field	Type	Description
`userId`	string	Engineer user ID
`role`	`"owner"` \| `"admin"` \| `"engineer"`	Organisation role
`canManageSchedule`	boolean	Whether the user can manage the scheduler
`canBeScheduled`	boolean	Whether the user can receive job assignments
`schedulerProfile`	object \| null	Availability and capacity settings
`user`	object	`{ id, name, email }`

Defaults and constants

Constant	Value	Used by
`DEFAULT_INSPECTION_FLEX_DAYS`	21	Inspection scheduling flex
`DEFAULT_WORK_FLEX_DAYS`	14	Work order scheduling flex
`DEFAULT_SHIFT_START_MINUTES`	480 (08:00)	Day-run and capacity calculations
`DEFAULT_SHIFT_END_MINUTES`	1020 (17:00)	Day-run and capacity calculations
`VALID_EQUIPMENT`	7 values	Equipment validation set
Max bulk update	100 jobs	Bulk update endpoint
Max batch inspections	50	Batch creation endpoint
Duration range	15-1440 minutes	All scheduling endpoints
Flex range	0-120 days	All scheduling endpoints
Crew range	1-50	All scheduling endpoints

How the scheduler connects to other workspaces

Workspace	Connection
Inspections	Created in the portal or via batch import, appear as schedulable jobs
Work orders	Created from accepted quotes or standalone, carry hold/resume lifecycle
Sites	Provide geographic data, scheduling rules, and access notes
Engineers	Form the assignment pool; availability and competencies tracked by capacity system
Deployment	Pushes scheduled work to the engineer's mobile day run
Finance	Follows after completed work; scheduler surfaces jobs needing invoicing
AI Assistant	Can be launched with current scheduler context for analysis