Data models · Route

Shared shapes used by the endpoint reference. Required fields, units, nullable values, and response-only properties are documented here.

Message

Field	Type	Description & constraints
`message`Required	`string`	Resource-specific value; see the related workflow and schema.

Example Message

{
  "message": "example"
}

Full schema

{
  "type": "object",
  "required": [
    "message"
  ],
  "properties": {
    "message": {
      "type": "string"
    }
  }
}

User

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`email`Required	`string`	Account email address.Format: email
`display_name`Required	`string`	Resource-specific value; see the related workflow and schema.

Example User

{
  "id": "11111111-1111-4111-8111-111111111111",
  "email": "dispatcher@example.com",
  "display_name": "Alex"
}

Full schema

{
  "type": "object",
  "required": [
    "id",
    "email",
    "display_name"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "display_name": {
      "type": "string"
    }
  }
}

Business

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`name`Required	`string`	Human-readable name shown in the workspace.
`time_zone`Required	`string`	Named IANA time zone, validated by the backend.
`deleted_at`	`string \| null`	System-managed UTC soft-deletion instant; null for active records.Format: date-time
`deleted_by`	`string \| null`	Deletion actor retained for history.Format: uuid

Example Business

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example Services",
  "time_zone": "Europe/Warsaw",
  "deleted_at": "2026-11-02T09:00:00Z",
  "deleted_by": "11111111-1111-4111-8111-111111111111"
}

Full schema

{
  "type": "object",
  "required": [
    "id",
    "name",
    "time_zone"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "time_zone": {
      "type": "string",
      "description": "Named IANA time zone, validated by the backend."
    },
    "deleted_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "System-managed UTC soft-deletion instant; null for active records."
    },
    "deleted_by": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Deletion actor retained for history."
    }
  }
}

Account

Field	Type	Description & constraints
`user`Required	`object`	Resource-specific value; see the related workflow and schema.
`businesses`Required	`array<object>`	Resource-specific value; see the related workflow and schema.

user fields

Field	Type	Description & constraints
`user.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`user.email`Required	`string`	Account email address.Format: email
`user.display_name`Required	`string`	Resource-specific value; see the related workflow and schema.

businesses[] fields

Field	Type	Description & constraints
`businesses.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`businesses.name`Required	`string`	Human-readable name shown in the workspace.
`businesses.time_zone`Required	`string`	Named IANA time zone, validated by the backend.
`businesses.deleted_at`	`string \| null`	System-managed UTC soft-deletion instant; null for active records.Format: date-time
`businesses.deleted_by`	`string \| null`	Deletion actor retained for history.Format: uuid

Example Account

{
  "user": {
    "id": "11111111-1111-4111-8111-111111111111",
    "email": "dispatcher@example.com",
    "display_name": "Alex"
  },
  "businesses": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Example Services",
      "time_zone": "Europe/Warsaw",
      "deleted_at": "2026-11-02T09:00:00Z",
      "deleted_by": "11111111-1111-4111-8111-111111111111"
    }
  ]
}

Full schema

{
  "type": "object",
  "required": [
    "user",
    "businesses"
  ],
  "properties": {
    "user": {
      "$ref": "#/components/schemas/User"
    },
    "businesses": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Business"
      }
    }
  }
}

LoginResponse

Field	Type	Description & constraints
`token`Required	`string`	Opaque bearer session token. Keep private.
`user`Required	`object`	Resource-specific value; see the related workflow and schema.
`businesses`Required	`array<object>`	Resource-specific value; see the related workflow and schema.

user fields

Field	Type	Description & constraints
`user.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`user.email`Required	`string`	Account email address.Format: email
`user.display_name`Required	`string`	Resource-specific value; see the related workflow and schema.

businesses[] fields

Field	Type	Description & constraints
`businesses.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`businesses.name`Required	`string`	Human-readable name shown in the workspace.
`businesses.time_zone`Required	`string`	Named IANA time zone, validated by the backend.
`businesses.deleted_at`	`string \| null`	System-managed UTC soft-deletion instant; null for active records.Format: date-time
`businesses.deleted_by`	`string \| null`	Deletion actor retained for history.Format: uuid

Example LoginResponse

{
  "token": "REPLACE_WITH_TOKEN",
  "user": {
    "id": "11111111-1111-4111-8111-111111111111",
    "email": "dispatcher@example.com",
    "display_name": "Alex"
  },
  "businesses": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Example Services",
      "time_zone": "Europe/Warsaw",
      "deleted_at": "2026-11-02T09:00:00Z",
      "deleted_by": "11111111-1111-4111-8111-111111111111"
    }
  ]
}

Full schema

{
  "type": "object",
  "required": [
    "token",
    "user",
    "businesses"
  ],
  "properties": {
    "token": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "Opaque bearer session token. Keep private."
    },
    "user": {
      "$ref": "#/components/schemas/User"
    },
    "businesses": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Business"
      }
    }
  }
}

RegisterRequest

Field	Type	Description & constraints
`email`Required	`string`	Account email address.Format: email · Max length: 254
`password`Required	`string`	Private chosen password; never expose it in client bundles or logs.Min length: 12 · Max length: 128 · Write only
`display_name`Required	`string`	Resource-specific value; see the related workflow and schema.Min length: 1 · Max length: 120
`business_name`Required	`string`	Resource-specific value; see the related workflow and schema.Min length: 1 · Max length: 120

Example RegisterRequest

{
  "email": "dispatcher@example.com",
  "password": "Example-passphrase-42!",
  "display_name": "Alex",
  "business_name": "Example Services"
}

Full schema

{
  "type": "object",
  "required": [
    "email",
    "password",
    "display_name",
    "business_name"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "password": {
      "type": "string",
      "minLength": 12,
      "maxLength": 128,
      "writeOnly": true
    },
    "display_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "business_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    }
  }
}

LoginRequest

Field	Type	Description & constraints
`email`Required	`string`	Account email address.Format: email
`password`Required	`string`	Private chosen password; never expose it in client bundles or logs.Write only

Example LoginRequest

{
  "email": "dispatcher@example.com",
  "password": "Example-passphrase-42!"
}

Full schema

{
  "type": "object",
  "required": [
    "email",
    "password"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "writeOnly": true
    }
  }
}

TokenRequest

Field	Type	Description & constraints
`token`Required	`string`	Private bearer/challenge token returned by the appropriate authentication flow.Write only

Example TokenRequest

{
  "token": "REPLACE_WITH_TOKEN"
}

Full schema

{
  "type": "object",
  "required": [
    "token"
  ],
  "properties": {
    "token": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$",
      "writeOnly": true
    }
  }
}

ResetRequest

Field	Type	Description & constraints
`email`Required	`string`	Account email address.Format: email

Example ResetRequest

{
  "email": "dispatcher@example.com"
}

Full schema

{
  "type": "object",
  "required": [
    "email"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    }
  }
}

ResetCompleteRequest

Field	Type	Description & constraints
`token`Required	`string`	Private bearer/challenge token returned by the appropriate authentication flow.Write only
`password`Required	`string`	Private chosen password; never expose it in client bundles or logs.Min length: 12 · Max length: 128 · Write only

Example ResetCompleteRequest

{
  "token": "REPLACE_WITH_TOKEN",
  "password": "Example-passphrase-42!"
}

Full schema

{
  "type": "object",
  "required": [
    "token",
    "password"
  ],
  "properties": {
    "token": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$",
      "writeOnly": true
    },
    "password": {
      "type": "string",
      "minLength": 12,
      "maxLength": 128,
      "writeOnly": true
    }
  }
}

BusinessWrite

Field	Type	Description & constraints
`name`Required	`string`	Human-readable name shown in the workspace.Min length: 1 · Max length: 120
`time_zone`Required	`string`	Resource-specific value; see the related workflow and schema.

Example BusinessWrite

{
  "name": "Example Services",
  "time_zone": "Europe/Warsaw"
}

Full schema

{
  "type": "object",
  "required": [
    "name",
    "time_zone"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "time_zone": {
      "type": "string",
      "examples": [
        "Europe/Warsaw",
        "UTC"
      ]
    }
  }
}

Error

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Example Error

{
  "error": {
    "code": "validation",
    "message": "example"
  }
}

Full schema

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "validation",
            "unauthorized",
            "not_found",
            "conflict",
            "unavailable",
            "rate_limited"
          ]
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Health

Field	Type	Description & constraints
`status`Required	`ok`	Current execution or operation state. Planned/unplanned is separate from execution.

Example Health

{
  "status": "ok"
}

Full schema

{
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ok"
      ]
    }
  }
}

Ready

Field	Type	Description & constraints
`status`Required	`ready`	Current execution or operation state. Planned/unplanned is separate from execution.

Example Ready

{
  "status": "ready"
}

Full schema

{
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ready"
      ]
    }
  }
}

Record

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`created_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`updated_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`revision`	`integer`	Current version used to detect stale edits or publication.
`deleted_at`	`string \| null`	System-managed UTC soft-deletion instant; null for active records.Format: date-time
`deleted_by`	`string \| null`	Deletion actor retained for history.Format: uuid

Example Record

{
  "id": "example-id",
  "created_at": "2026-11-02T09:00:00Z",
  "updated_at": "2026-11-02T09:00:00Z",
  "revision": 1,
  "deleted_at": "2026-11-02T09:00:00Z",
  "deleted_by": "11111111-1111-4111-8111-111111111111"
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
    },
    "revision": {
      "type": "integer"
    },
    "deleted_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "System-managed UTC soft-deletion instant; null for active records."
    },
    "deleted_by": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Deletion actor retained for history."
    }
  },
  "additionalProperties": true
}

Location

Field	Type	Description & constraints
`latitude`Required	`number`	Latitude in decimal degrees, from -90 to 90.Min: -90 · Max: 90
`longitude`Required	`number`	Longitude in decimal degrees, from -180 to 180.Min: -180 · Max: 180

Example Location

{
  "latitude": 52.2297,
  "longitude": 21.0122
}

Full schema

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    }
  },
  "required": [
    "latitude",
    "longitude"
  ]
}

WorkingInterval

Field	Type	Description & constraints
`start`Required	`string`	Start instant or working-interval start, as specified by this field’s format.
`end`Required	`string`	End instant or working-interval end; must follow the effective start.
`end_day_offset`	`integer`	Use 1 when the working interval ends the following day.Min: 0

Example WorkingInterval

{
  "start": "2026-11-02T08:00:00Z",
  "end": "2026-11-02T16:00:00Z",
  "end_day_offset": 1
}

Full schema

{
  "type": "object",
  "properties": {
    "start": {
      "type": "string",
      "pattern": "^[0-9]{2}:[0-9]{2}$"
    },
    "end": {
      "type": "string",
      "pattern": "^[0-9]{2}:[0-9]{2}$"
    },
    "end_day_offset": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "start",
    "end"
  ]
}

WorkingHours

Field	Type	Description & constraints
`weekly`Required	`object`	0=Monday through6=Sunday
`overrides`Required	`object`	Calendar-date keys replace that entire date, including prior-night carryover. Empty array means unavailable.
`gap_policy`	`return_to_warehouse \| wait`	Resource-specific value; see the related workflow and schema.

Example WorkingHours

{
  "weekly": {},
  "overrides": {},
  "gap_policy": "return_to_warehouse"
}

Full schema

{
  "type": "object",
  "properties": {
    "weekly": {
      "type": "object",
      "description": "0=Monday through6=Sunday",
      "additionalProperties": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/WorkingInterval"
        }
      }
    },
    "overrides": {
      "type": "object",
      "description": "Calendar-date keys replace that entire date, including prior-night carryover. Empty array means unavailable.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/WorkingInterval"
        }
      }
    },
    "gap_policy": {
      "type": "string",
      "enum": [
        "return_to_warehouse",
        "wait"
      ]
    }
  },
  "required": [
    "weekly",
    "overrides"
  ]
}

Warehouse

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`location`Required	`object`	Service or record location, using latitude/longitude in decimal degrees.

location fields

Field	Type	Description & constraints
`location.latitude`Required	`number`	Latitude in decimal degrees, from -90 to 90.Min: -90 · Max: 90
`location.longitude`Required	`number`	Longitude in decimal degrees, from -180 to 180.Min: -180 · Max: 180

Example Warehouse

{
  "id": "example-id",
  "name": "Example Services",
  "location": {
    "latitude": 52.2297,
    "longitude": 21.0122
  }
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "location": {
      "$ref": "#/components/schemas/Location"
    }
  },
  "required": [
    "name",
    "location"
  ]
}

Vehicle

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`warehouse_id`Required	`string`	Warehouse used as this vehicle’s route origin/return location.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`color`	`string`	Resource-specific value; see the related workflow and schema.
`height_meters`	`number \| null`	Resource-specific value; see the related workflow and schema.
`weight_kg`	`number \| null`	Resource-specific value; see the related workflow and schema.
`working_hours`	`object`	Vehicle availability: weekly weekday intervals plus calendar-date overrides.

working_hours fields

Field	Type	Description & constraints
`working_hours.weekly`Required	`object`	0=Monday through6=Sunday
`working_hours.overrides`Required	`object`	Calendar-date keys replace that entire date, including prior-night carryover. Empty array means unavailable.
`working_hours.gap_policy`	`return_to_warehouse \| wait`	Resource-specific value; see the related workflow and schema.

Example Vehicle

{
  "id": "example-id",
  "name": "Example Services",
  "warehouse_id": "warehouse-01",
  "driver_id": "driver-01",
  "color": "#35735a",
  "height_meters": 1,
  "weight_kg": 1,
  "working_hours": {
    "weekly": {},
    "overrides": {},
    "gap_policy": "return_to_warehouse"
  }
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "warehouse_id": {
      "type": "string"
    },
    "driver_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "color": {
      "type": "string"
    },
    "height_meters": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "weight_kg": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "working_hours": {
      "$ref": "#/components/schemas/WorkingHours"
    }
  },
  "required": [
    "name",
    "warehouse_id"
  ],
  "additionalProperties": true
}

Driver

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`email`Required	`string`	Account email address.Format: email
`active`	`boolean`	Whether this account or integration is enabled.
`duty_status`	`online \| offline`	Resource-specific value; see the related workflow and schema.
`location`	`object \| null`	Service or record location, using latitude/longitude in decimal degrees.
`duty_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`activation_code`	`string`	Returned once during provisioning/reset; administrator delivers it to driver.Response only

Example Driver

{
  "id": "example-id",
  "name": "Example Services",
  "email": "dispatcher@example.com",
  "active": true,
  "duty_status": "online",
  "location": {
    "latitude": 52.2297,
    "longitude": 21.0122
  },
  "duty_started_at": "2026-11-02T09:00:00Z",
  "activation_code": "example"
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "active": {
      "type": "boolean"
    },
    "duty_status": {
      "enum": [
        "online",
        "offline"
      ]
    },
    "location": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/Location"
        },
        {
          "type": "null"
        }
      ]
    },
    "duty_started_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
        },
        {
          "type": "null"
        }
      ]
    },
    "activation_code": {
      "type": "string",
      "readOnly": true,
      "description": "Returned once during provisioning/reset; administrator delivers it to driver."
    }
  },
  "required": [
    "name",
    "email"
  ],
  "additionalProperties": true
}

Order

Field	Type	Description & constraints
`id`	`string`	Optional on creation; generated if absent. Unique within authorized business; duplicates409 even if payload matches.Max length: 120
`type`	`task \| break`	Record or field type; choose one of the listed values.
`location`Required	`object`	Service or record location, using latitude/longitude in decimal degrees.
`duration_seconds`Required	`integer`	Time needed to do the work, excluding travel, in seconds.Min: 1
`window_start`Required	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`window_end`Required	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled`	Live execution status. Administrator changes become pending_status until publication.
`pending_status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled \| null`	Resource-specific value; see the related workflow and schema.
`scheduled_at`	`string \| null`	Planned service-start instant; absence indicates unplanned work.
`vehicle_id`	`string \| null`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`replacement_driver_id`	`string \| null`	Administrator-selected replacement driver for a handover break.
`custom_fields`	`object`	Values keyed by the business-defined custom field IDs. Existing orders retain their schema version.
`schema_snapshot`	`object`	Immutable field definition/type/permission version for this order.Response only
`actual_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`actual_completed_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

location fields

Field	Type	Description & constraints
`location.latitude`Required	`number`	Latitude in decimal degrees, from -90 to 90.Min: -90 · Max: 90
`location.longitude`Required	`number`	Longitude in decimal degrees, from -180 to 180.Min: -180 · Max: 180

Example Order

{
  "id": "example-id",
  "type": "task",
  "location": {
    "latitude": 52.2297,
    "longitude": 21.0122
  },
  "duration_seconds": 1800,
  "window_start": "2026-11-02T09:00:00Z",
  "window_end": "2026-11-02T12:00:00Z",
  "status": "created",
  "pending_status": "created",
  "scheduled_at": "2026-11-02T09:30:00Z",
  "vehicle_id": "van-01",
  "driver_id": "driver-01",
  "replacement_driver_id": "example",
  "custom_fields": {},
  "schema_snapshot": {},
  "actual_started_at": "2026-11-02T09:00:00Z",
  "actual_completed_at": "2026-11-02T09:00:00Z"
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional on creation; generated if absent. Unique within authorized business; duplicates409 even if payload matches."
    },
    "type": {
      "enum": [
        "task",
        "break"
      ]
    },
    "location": {
      "$ref": "#/components/schemas/Location"
    },
    "duration_seconds": {
      "type": "integer",
      "minimum": 1
    },
    "window_start": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
    },
    "window_end": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
    },
    "status": {
      "enum": [
        "created",
        "on_road",
        "in_progress",
        "completed",
        "unable_to_complete",
        "cancelled"
      ],
      "description": "Live execution status. Administrator changes become pending_status until publication."
    },
    "pending_status": {
      "anyOf": [
        {
          "enum": [
            "created",
            "on_road",
            "in_progress",
            "completed",
            "unable_to_complete",
            "cancelled"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "scheduled_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
        },
        {
          "type": "null"
        }
      ]
    },
    "vehicle_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "driver_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "replacement_driver_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "custom_fields": {
      "type": "object",
      "additionalProperties": true
    },
    "schema_snapshot": {
      "type": "object",
      "readOnly": true,
      "description": "Immutable field definition/type/permission version for this order."
    },
    "actual_started_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
        },
        {
          "type": "null"
        }
      ]
    },
    "actual_completed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "location",
    "duration_seconds",
    "window_start",
    "window_end"
  ],
  "additionalProperties": true
}

FieldDefinition

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`type`Required	`text \| number \| date \| datetime \| boolean \| select`	Record or field type; choose one of the listed values.
`required`	`boolean`	Whether a value is mandatory.
`driver_visible`	`boolean`	Whether drivers can see the field.
`driver_editable`	`boolean`	Whether drivers can edit the field; hidden fields cannot be editable.
`multiple`	`boolean`	Allow multiple dropdown choices when true.
`choices`	`array<object>`	Allowed dropdown options with stable IDs and labels.

choices[] fields

Field	Type	Description & constraints
`choices.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`choices.label`Required	`string`	Resource-specific value; see the related workflow and schema.

Example FieldDefinition

{
  "id": "example-id",
  "name": "Example Services",
  "type": "text",
  "required": false,
  "driver_visible": false,
  "driver_editable": false,
  "multiple": false,
  "choices": [
    {
      "id": "example-id",
      "label": "example"
    }
  ]
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "type": {
      "enum": [
        "text",
        "number",
        "date",
        "datetime",
        "boolean",
        "select"
      ]
    },
    "required": {
      "type": "boolean"
    },
    "driver_visible": {
      "type": "boolean"
    },
    "driver_editable": {
      "type": "boolean"
    },
    "multiple": {
      "type": "boolean"
    },
    "choices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "label"
        ]
      }
    }
  },
  "required": [
    "id",
    "name",
    "type"
  ]
}

CustomSchema

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`fields`Required	`array<object>`	Custom-field definitions captured for new orders.

fields[] fields

Field	Type	Description & constraints
`fields.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`fields.name`Required	`string`	Human-readable name shown in the workspace.
`fields.type`Required	`text \| number \| date \| datetime \| boolean \| select`	Record or field type; choose one of the listed values.
`fields.required`	`boolean`	Whether a value is mandatory.
`fields.driver_visible`	`boolean`	Whether drivers can see the field.
`fields.driver_editable`	`boolean`	Whether drivers can edit the field; hidden fields cannot be editable.
`fields.multiple`	`boolean`	Allow multiple dropdown choices when true.
`fields.choices`	`array<object>`	Allowed dropdown options with stable IDs and labels.

fields.choices[] fields

Field	Type	Description & constraints
`fields.choices.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`fields.choices.label`Required	`string`	Resource-specific value; see the related workflow and schema.

Example CustomSchema

{
  "id": "example-id",
  "name": "Example Services",
  "fields": [
    {
      "id": "example-id",
      "name": "Example Services",
      "type": "text",
      "required": false,
      "driver_visible": false,
      "driver_editable": false,
      "multiple": false,
      "choices": [
        {
          "id": "example-id",
          "label": "example"
        }
      ]
    }
  ]
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "fields": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/FieldDefinition"
      }
    }
  },
  "required": [
    "name",
    "fields"
  ]
}

Webhook

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`url`Required	`string`	HTTPS destination for webhook deliveries.Format: uri
`events`Required	`array<string>`	Subscribed event names; use * for all supported events.
`active`	`boolean`	Whether this account or integration is enabled.
`secret`	`string`	Private shared webhook-signing secret.

Example Webhook

{
  "id": "example-id",
  "name": "Example Services",
  "url": "https://client.example.com/webhooks/route",
  "events": [
    "*"
  ],
  "active": true,
  "secret": "REPLACE_WITH_WEBHOOK_SECRET"
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "active": {
      "type": "boolean"
    },
    "secret": {
      "type": "string"
    }
  },
  "required": [
    "name",
    "url",
    "events"
  ]
}

Region

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`geometry`Required	`object`	GeoJSON Polygon; coordinates are longitude/latitude.
`status`	`not_installed \| queued \| running \| installing \| ready \| failed \| building`	Current execution or operation state. Planned/unplanned is separate from execution.
`job_id`	`string \| null`	Resource-specific value; see the related workflow and schema.
`dataset_version`	`string \| null`	Resource-specific value; see the related workflow and schema.
`error`	`string \| null`	Resource-specific value; see the related workflow and schema.

geometry fields

Field	Type	Description & constraints
`geometry.type`	`Polygon`	Record or field type; choose one of the listed values.
`geometry.coordinates`	`array<array<array<number>>>`	Resource-specific value; see the related workflow and schema.

Example Region

{
  "id": "example-id",
  "name": "Example Services",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          1
        ]
      ]
    ]
  },
  "status": "not_installed",
  "job_id": "11111111-1111-4111-8111-111111111111",
  "dataset_version": "example",
  "error": "example"
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "geometry": {
      "type": "object",
      "description": "GeoJSON Polygon; coordinates are longitude/latitude.",
      "properties": {
        "type": {
          "const": "Polygon"
        },
        "coordinates": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "number"
              }
            }
          }
        }
      }
    },
    "status": {
      "enum": [
        "not_installed",
        "queued",
        "running",
        "installing",
        "ready",
        "failed",
        "building"
      ]
    },
    "job_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "dataset_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "name",
    "geometry"
  ],
  "additionalProperties": true
}

Scenario

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`nodes`Required	`array<object>`	Graph vertices.
`edges`Required	`array<object>`	Directed graph connections with travel costs.
`orders`	`array<object>`	Resource-specific value; see the related workflow and schema.
`warehouses`	`array<object>`	Resource-specific value; see the related workflow and schema.
`vehicles`	`array<object>`	Resource-specific value; see the related workflow and schema.
`drivers`	`array<object>`	Resource-specific value; see the related workflow and schema.

nodes[] fields

Field	Type	Description & constraints
`nodes.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`nodes.x`Required	`number`	Resource-specific value; see the related workflow and schema.
`nodes.y`Required	`number`	Resource-specific value; see the related workflow and schema.

edges[] fields

Field	Type	Description & constraints
`edges.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`edges.from`Required	`string`	Resource-specific value; see the related workflow and schema.
`edges.to`Required	`string`	Resource-specific value; see the related workflow and schema.
`edges.time_seconds`Required	`number`	Resource-specific value; see the related workflow and schema.
`edges.distance_meters`Required	`number`	Resource-specific value; see the related workflow and schema.
`edges.bidirectional`	`boolean`	Resource-specific value; see the related workflow and schema.
`edges.reverse_time_seconds`	`number`	Resource-specific value; see the related workflow and schema.
`edges.reverse_distance_meters`	`number`	Resource-specific value; see the related workflow and schema.

Example Scenario

{
  "id": "example-id",
  "name": "Example Services",
  "nodes": [
    {
      "id": "example-id",
      "x": 1,
      "y": 1
    }
  ],
  "edges": [
    {
      "id": "example-id",
      "from": "example",
      "to": "example",
      "time_seconds": 1,
      "distance_meters": 1,
      "bidirectional": false,
      "reverse_time_seconds": 1,
      "reverse_distance_meters": 1
    }
  ],
  "orders": [
    {}
  ],
  "warehouses": [
    {}
  ],
  "vehicles": [
    {}
  ],
  "drivers": [
    {}
  ]
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "x": {
            "type": "number"
          },
          "y": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "x",
          "y"
        ]
      }
    },
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "time_seconds": {
            "type": "number"
          },
          "distance_meters": {
            "type": "number"
          },
          "bidirectional": {
            "type": "boolean"
          },
          "reverse_time_seconds": {
            "type": "number"
          },
          "reverse_distance_meters": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "from",
          "to",
          "time_seconds",
          "distance_meters"
        ]
      }
    },
    "orders": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Order constraints; graph location uses vertex_id or edge_id+offset+explicit segment times/distances.",
        "additionalProperties": true
      }
    },
    "warehouses": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "vehicles": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "drivers": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    }
  },
  "required": [
    "name",
    "nodes",
    "edges"
  ],
  "additionalProperties": true
}

Plan

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`vehicle_id`Required	`string`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`revision`Required	`integer`	Current version used to detect stale edits or publication.
`state`Required	`planning \| published \| superseded`	Planning/published version state or event visibility state.
`start_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`end_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`stops`Required	`array<object>`	Ordered planned route stops.
`return_leg`	`object`	Resource-specific value; see the related workflow and schema.
`warnings`	`array<string>`	Constraint warnings requiring review where applicable.
`unplanned_order_ids`	`array<string>`	Resource-specific value; see the related workflow and schema.
`published`	`object \| null`	Resource-specific value; see the related workflow and schema.
`received_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

Example Plan

{
  "id": "example-id",
  "vehicle_id": "van-01",
  "driver_id": "driver-01",
  "revision": 1,
  "state": "planning",
  "start_at": "2026-11-02T08:00:00Z",
  "end_at": "2026-11-02T16:00:00Z",
  "stops": [
    {}
  ],
  "return_leg": {},
  "warnings": [
    "example"
  ],
  "unplanned_order_ids": [
    "example"
  ],
  "published": {},
  "received_at": "2026-11-02T09:00:00Z"
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "vehicle_id": {
      "type": "string"
    },
    "driver_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "revision": {
      "type": "integer"
    },
    "state": {
      "enum": [
        "planning",
        "published",
        "superseded"
      ]
    },
    "start_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
    },
    "end_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
    },
    "stops": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "return_leg": {
      "type": "object",
      "additionalProperties": true
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "unplanned_order_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "published": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    },
    "received_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id",
    "vehicle_id",
    "revision",
    "state",
    "stops"
  ],
  "additionalProperties": true
}

OperationalSettings

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`time_zone`Required	`string`	Resource-specific value; see the related workflow and schema.
`planning`	`object`	Business planning preferences.
`evidence`	`object`	Shared completion-evidence requirements.
`routing`	`object`	Local road-routing engine and approved-dataset update schedule.

planning fields

Field	Type	Description & constraints
`planning.travel_metric`	`time \| distance \| null`	Resource-specific value; see the related workflow and schema.
`planning.objectives`	`array<completed_tasks \| travel>`	Planning objectives; completing more work and minimizing travel can be combined.
`planning.location_freshness_seconds`	`integer`	Resource-specific value; see the related workflow and schema.
`planning.min_rest_seconds`	`integer \| null`	Resource-specific value; see the related workflow and schema.
`planning.notify_unplanned`	`boolean`	Resource-specific value; see the related workflow and schema.

evidence fields

Field	Type	Description & constraints
`evidence.require_photos`	`boolean`	Resource-specific value; see the related workflow and schema.
`evidence.require_signature`	`boolean`	Resource-specific value; see the related workflow and schema.

routing fields

Field	Type	Description & constraints
`routing.engine`	`osrm \| valhalla`	Resource-specific value; see the related workflow and schema.
`routing.update_schedule`	`string`	Five-field cron in business time zone. Weekly Sunday03:00 default; approved regions only.

Example OperationalSettings

{
  "id": "example-id",
  "name": "Example Services",
  "time_zone": "Europe/Warsaw",
  "planning": {
    "travel_metric": "time",
    "objectives": [
      "completed_tasks",
      "travel"
    ],
    "location_freshness_seconds": 1,
    "min_rest_seconds": 1,
    "notify_unplanned": false
  },
  "evidence": {
    "require_photos": false,
    "require_signature": false
  },
  "routing": {
    "engine": "osrm",
    "update_schedule": "example"
  }
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "time_zone": {
      "type": "string"
    },
    "planning": {
      "type": "object",
      "properties": {
        "travel_metric": {
          "anyOf": [
            {
              "enum": [
                "time",
                "distance"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "objectives": {
          "type": "array",
          "items": {
            "enum": [
              "completed_tasks",
              "travel"
            ]
          }
        },
        "location_freshness_seconds": {
          "type": "integer"
        },
        "min_rest_seconds": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "null"
            }
          ]
        },
        "notify_unplanned": {
          "type": "boolean"
        }
      }
    },
    "evidence": {
      "type": "object",
      "properties": {
        "require_photos": {
          "type": "boolean"
        },
        "require_signature": {
          "type": "boolean"
        }
      }
    },
    "routing": {
      "type": "object",
      "properties": {
        "engine": {
          "enum": [
            "osrm",
            "valhalla"
          ]
        },
        "update_schedule": {
          "type": "string",
          "description": "Five-field cron in business time zone. Weekly Sunday03:00 default; approved regions only."
        }
      }
    }
  },
  "required": [
    "name",
    "time_zone"
  ],
  "additionalProperties": true
}

ResourceRecord

Actual resource-specific shape; generic records include system metadata.

Field	Type	Description & constraints
`id`	`string`	Optional on creation; generated if absent. Unique within authorized business; duplicates409 even if payload matches.Max length: 120
`type`	`task \| break`	Record or field type; choose one of the listed values.
`location`Required	`object`	Service or record location, using latitude/longitude in decimal degrees.
`duration_seconds`Required	`integer`	Time needed to do the work, excluding travel, in seconds.Min: 1
`window_start`Required	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`window_end`Required	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled`	Live execution status. Administrator changes become pending_status until publication.
`pending_status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled \| null`	Resource-specific value; see the related workflow and schema.
`scheduled_at`	`string \| null`	Planned service-start instant; absence indicates unplanned work.
`vehicle_id`	`string \| null`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`replacement_driver_id`	`string \| null`	Administrator-selected replacement driver for a handover break.
`custom_fields`	`object`	Values keyed by the business-defined custom field IDs. Existing orders retain their schema version.
`schema_snapshot`	`object`	Immutable field definition/type/permission version for this order.Response only
`actual_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`actual_completed_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

location fields

Field	Type	Description & constraints
`location.latitude`Required	`number`	Latitude in decimal degrees, from -90 to 90.Min: -90 · Max: 90
`location.longitude`Required	`number`	Longitude in decimal degrees, from -180 to 180.Min: -180 · Max: 180

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`warehouse_id`Required	`string`	Warehouse used as this vehicle’s route origin/return location.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`color`	`string`	Resource-specific value; see the related workflow and schema.
`height_meters`	`number \| null`	Resource-specific value; see the related workflow and schema.
`weight_kg`	`number \| null`	Resource-specific value; see the related workflow and schema.
`working_hours`	`object`	Vehicle availability: weekly weekday intervals plus calendar-date overrides.

working_hours fields

Field	Type	Description & constraints
`working_hours.weekly`Required	`object`	0=Monday through6=Sunday
`working_hours.overrides`Required	`object`	Calendar-date keys replace that entire date, including prior-night carryover. Empty array means unavailable.
`working_hours.gap_policy`	`return_to_warehouse \| wait`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`email`Required	`string`	Account email address.Format: email
`active`	`boolean`	Whether this account or integration is enabled.
`duty_status`	`online \| offline`	Resource-specific value; see the related workflow and schema.
`location`	`object \| null`	Service or record location, using latitude/longitude in decimal degrees.
`duty_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`activation_code`	`string`	Returned once during provisioning/reset; administrator delivers it to driver.Response only

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`location`Required	`object`	Service or record location, using latitude/longitude in decimal degrees.

location fields

Field	Type	Description & constraints
`location.latitude`Required	`number`	Latitude in decimal degrees, from -90 to 90.Min: -90 · Max: 90
`location.longitude`Required	`number`	Longitude in decimal degrees, from -180 to 180.Min: -180 · Max: 180

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`fields`Required	`array<object>`	Custom-field definitions captured for new orders.

fields[] fields

Field	Type	Description & constraints
`fields.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`fields.name`Required	`string`	Human-readable name shown in the workspace.
`fields.type`Required	`text \| number \| date \| datetime \| boolean \| select`	Record or field type; choose one of the listed values.
`fields.required`	`boolean`	Whether a value is mandatory.
`fields.driver_visible`	`boolean`	Whether drivers can see the field.
`fields.driver_editable`	`boolean`	Whether drivers can edit the field; hidden fields cannot be editable.
`fields.multiple`	`boolean`	Allow multiple dropdown choices when true.
`fields.choices`	`array<object>`	Allowed dropdown options with stable IDs and labels.

fields.choices[] fields

Field	Type	Description & constraints
`fields.choices.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`fields.choices.label`Required	`string`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`url`Required	`string`	HTTPS destination for webhook deliveries.Format: uri
`events`Required	`array<string>`	Subscribed event names; use * for all supported events.
`active`	`boolean`	Whether this account or integration is enabled.
`secret`	`string`	Private shared webhook-signing secret.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`geometry`Required	`object`	GeoJSON Polygon; coordinates are longitude/latitude.
`status`	`not_installed \| queued \| running \| installing \| ready \| failed \| building`	Current execution or operation state. Planned/unplanned is separate from execution.
`job_id`	`string \| null`	Resource-specific value; see the related workflow and schema.
`dataset_version`	`string \| null`	Resource-specific value; see the related workflow and schema.
`error`	`string \| null`	Resource-specific value; see the related workflow and schema.

geometry fields

Field	Type	Description & constraints
`geometry.type`	`Polygon`	Record or field type; choose one of the listed values.
`geometry.coordinates`	`array<array<array<number>>>`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`nodes`Required	`array<object>`	Graph vertices.
`edges`Required	`array<object>`	Directed graph connections with travel costs.
`orders`	`array<object>`	Resource-specific value; see the related workflow and schema.
`warehouses`	`array<object>`	Resource-specific value; see the related workflow and schema.
`vehicles`	`array<object>`	Resource-specific value; see the related workflow and schema.
`drivers`	`array<object>`	Resource-specific value; see the related workflow and schema.

nodes[] fields

Field	Type	Description & constraints
`nodes.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`nodes.x`Required	`number`	Resource-specific value; see the related workflow and schema.
`nodes.y`Required	`number`	Resource-specific value; see the related workflow and schema.

edges[] fields

Field	Type	Description & constraints
`edges.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`edges.from`Required	`string`	Resource-specific value; see the related workflow and schema.
`edges.to`Required	`string`	Resource-specific value; see the related workflow and schema.
`edges.time_seconds`Required	`number`	Resource-specific value; see the related workflow and schema.
`edges.distance_meters`Required	`number`	Resource-specific value; see the related workflow and schema.
`edges.bidirectional`	`boolean`	Resource-specific value; see the related workflow and schema.
`edges.reverse_time_seconds`	`number`	Resource-specific value; see the related workflow and schema.
`edges.reverse_distance_meters`	`number`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`vehicle_id`Required	`string`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`revision`Required	`integer`	Current version used to detect stale edits or publication.
`state`Required	`planning \| published \| superseded`	Planning/published version state or event visibility state.
`start_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`end_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`stops`Required	`array<object>`	Ordered planned route stops.
`return_leg`	`object`	Resource-specific value; see the related workflow and schema.
`warnings`	`array<string>`	Constraint warnings requiring review where applicable.
`unplanned_order_ids`	`array<string>`	Resource-specific value; see the related workflow and schema.
`published`	`object \| null`	Resource-specific value; see the related workflow and schema.
`received_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`created_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`updated_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`revision`	`integer`	Current version used to detect stale edits or publication.
`deleted_at`	`string \| null`	System-managed UTC soft-deletion instant; null for active records.Format: date-time
`deleted_by`	`string \| null`	Deletion actor retained for history.Format: uuid

Example ResourceRecord

{
  "id": "example-id",
  "type": "task",
  "location": {
    "latitude": 52.2297,
    "longitude": 21.0122
  },
  "duration_seconds": 1800,
  "window_start": "2026-11-02T09:00:00Z",
  "window_end": "2026-11-02T12:00:00Z",
  "status": "created",
  "pending_status": "created",
  "scheduled_at": "2026-11-02T09:30:00Z",
  "vehicle_id": "van-01",
  "driver_id": "driver-01",
  "replacement_driver_id": "example",
  "custom_fields": {},
  "schema_snapshot": {},
  "actual_started_at": "2026-11-02T09:00:00Z",
  "actual_completed_at": "2026-11-02T09:00:00Z"
}

Full schema

{
  "description": "Actual resource-specific shape; generic records include system metadata.",
  "anyOf": [
    {
      "$ref": "#/components/schemas/Order"
    },
    {
      "$ref": "#/components/schemas/Vehicle"
    },
    {
      "$ref": "#/components/schemas/Driver"
    },
    {
      "$ref": "#/components/schemas/Warehouse"
    },
    {
      "$ref": "#/components/schemas/CustomSchema"
    },
    {
      "$ref": "#/components/schemas/Webhook"
    },
    {
      "$ref": "#/components/schemas/Region"
    },
    {
      "$ref": "#/components/schemas/Scenario"
    },
    {
      "$ref": "#/components/schemas/Plan"
    },
    {
      "$ref": "#/components/schemas/Record"
    }
  ]
}

PlanningRequest

Field	Type	Description & constraints
`vehicle_ids`Required	`array<string>`	IDs of eligible vehicles selected for the planning run.
`date_start`Required	`string`	First planning date in the business time zone.Format: date
`date_end`Required	`string`	Last planning date in the business time zone.Format: date
`dates`	`array<string>`	Explicit local calendar dates to consider, when supported.
`schedule_lock`	`boolean`	Preserve existing planned start times and relative stop order. Defaults to false.
`assignment_lock`	`boolean`	Preserve existing vehicle/driver assignments. Defaults to false.
`include_planned`	`boolean`	Include already-planned orders in the planning run. Defaults to false.
`objectives`	`array<completed_tasks \| travel>`	Planning objectives; completing more work and minimizing travel can be combined.

Example PlanningRequest

{
  "vehicle_ids": [
    "van-01"
  ],
  "date_start": "2026-11-02",
  "date_end": "2026-11-02",
  "dates": [
    "2026-11-02"
  ],
  "schedule_lock": false,
  "assignment_lock": false,
  "include_planned": false,
  "objectives": [
    "completed_tasks",
    "travel"
  ]
}

Full schema

{
  "type": "object",
  "properties": {
    "vehicle_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "date_start": {
      "type": "string",
      "format": "date"
    },
    "date_end": {
      "type": "string",
      "format": "date"
    },
    "dates": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "date"
      }
    },
    "schedule_lock": {
      "type": "boolean"
    },
    "assignment_lock": {
      "type": "boolean"
    },
    "include_planned": {
      "type": "boolean"
    },
    "objectives": {
      "type": "array",
      "items": {
        "enum": [
          "completed_tasks",
          "travel"
        ]
      }
    }
  },
  "required": [
    "vehicle_ids",
    "date_start",
    "date_end"
  ]
}

EvidenceUpload

Maximum binary payload10MiB; numeric JSON encoding is larger. Images are private and required evidence must be uploaded before completion.

Field	Type	Description & constraints
`kind`Required	`photo \| signature`	Photo or customer signature evidence.
`content_type`Required	`image/png \| image/jpeg \| image/webp`	MIME type of the image bytes.
`bytes`Required	`array<integer>`	Numeric byte array containing an actual supported image; not a base64 string.

Example EvidenceUpload

{
  "kind": "photo",
  "content_type": "image/png",
  "bytes": [
    1
  ]
}

Full schema

{
  "type": "object",
  "properties": {
    "kind": {
      "enum": [
        "photo",
        "signature"
      ]
    },
    "content_type": {
      "enum": [
        "image/png",
        "image/jpeg",
        "image/webp"
      ]
    },
    "bytes": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 255
      }
    }
  },
  "required": [
    "kind",
    "content_type",
    "bytes"
  ],
  "description": "Maximum binary payload10MiB; numeric JSON encoding is larger. Images are private and required evidence must be uploaded before completion."
}

DriverEvidenceMetadata

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`kind`Required	`photo \| signature`	Photo or customer signature evidence.
`content_type`Required	`image/png \| image/jpeg \| image/webp`	MIME type of the image bytes.
`size_bytes`	`integer`	Resource-specific value; see the related workflow and schema.
`created_at`	`string`	Resource-specific value; see the related workflow and schema.Format: date-time

Example DriverEvidenceMetadata

{
  "id": "11111111-1111-4111-8111-111111111111",
  "kind": "photo",
  "content_type": "image/png",
  "size_bytes": 1,
  "created_at": "2026-11-02T09:00:00Z"
}

Full schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "kind": {
      "enum": [
        "photo",
        "signature"
      ]
    },
    "content_type": {
      "enum": [
        "image/png",
        "image/jpeg",
        "image/webp"
      ]
    },
    "size_bytes": {
      "type": "integer"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "kind",
    "content_type"
  ]
}

DriverSessionResponse

Field	Type	Description & constraints
`token`Required	`string`	Opaque driver bearer token. Keep private.
`business_id`Required	`string`	Resource-specific value; see the related workflow and schema.Format: uuid
`driver`Required	`object`	Resource-specific value; see the related workflow and schema.
`expires_at`	`string`	Latest instant this temporary offer or session remains valid.Format: date-time

driver fields

Field	Type	Description & constraints
`driver.id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`driver.name`Required	`string`	Human-readable name shown in the workspace.
`driver.email`Required	`string`	Account email address.Format: email
`driver.active`	`boolean`	Whether this account or integration is enabled.
`driver.duty_status`	`online \| offline`	Resource-specific value; see the related workflow and schema.
`driver.location`	`object \| null`	Service or record location, using latitude/longitude in decimal degrees.
`driver.duty_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`driver.activation_code`	`string`	Returned once during provisioning/reset; administrator delivers it to driver.Response only

Example DriverSessionResponse

{
  "token": "REPLACE_WITH_TOKEN",
  "business_id": "11111111-1111-4111-8111-111111111111",
  "driver": {
    "id": "example-id",
    "name": "Example Services",
    "email": "dispatcher@example.com",
    "active": true,
    "duty_status": "online",
    "location": {
      "latitude": 52.2297,
      "longitude": 21.0122
    },
    "duty_started_at": "2026-11-02T09:00:00Z",
    "activation_code": "example"
  },
  "expires_at": "2026-11-02T09:00:00Z"
}

Full schema

{
  "type": "object",
  "required": [
    "token",
    "business_id",
    "driver"
  ],
  "properties": {
    "token": {
      "type": "string",
      "description": "Opaque driver bearer token. Keep private."
    },
    "business_id": {
      "type": "string",
      "format": "uuid"
    },
    "driver": {
      "$ref": "#/components/schemas/Driver"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

DriverBusinessChoices

Field	Type	Description & constraints
`requires_business_selection`Required	`true`	Resource-specific value; see the related workflow and schema.
`businesses`Required	`array<object>`	Resource-specific value; see the related workflow and schema.
`reauthenticate_on_selection`Required	`true`	Resource-specific value; see the related workflow and schema.

businesses[] fields

Field	Type	Description & constraints
`businesses.business_id`Required	`string`	Resource-specific value; see the related workflow and schema.Format: uuid
`businesses.name`Required	`string`	Human-readable name shown in the workspace.

Example DriverBusinessChoices

{
  "requires_business_selection": true,
  "businesses": [
    {
      "business_id": "11111111-1111-4111-8111-111111111111",
      "name": "Example Services"
    }
  ],
  "reauthenticate_on_selection": true
}

Full schema

{
  "type": "object",
  "required": [
    "requires_business_selection",
    "businesses",
    "reauthenticate_on_selection"
  ],
  "properties": {
    "requires_business_selection": {
      "const": true
    },
    "businesses": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "business_id",
          "name"
        ],
        "properties": {
          "business_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          }
        }
      }
    },
    "reauthenticate_on_selection": {
      "const": true
    }
  }
}

DriverSnapshot

Field	Type	Description & constraints
`business`Required	`object`	Resource-specific value; see the related workflow and schema.
`driver`Required	`object`	Resource-specific value; see the related workflow and schema.
`plans`Required	`array<object>`	Resource-specific value; see the related workflow and schema.
`orders`Required	`array<object>`	Resource-specific value; see the related workflow and schema.
`evidence_requirements`	`object`	Resource-specific value; see the related workflow and schema.
`last_refreshed_at`Required	`string`	Resource-specific value; see the related workflow and schema.Format: date-time
`warnings`	`array<string>`	Constraint warnings requiring review where applicable.

business fields

Field	Type	Description & constraints
`business.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`business.name`Required	`string`	Human-readable name shown in the workspace.
`business.time_zone`Required	`string`	Named IANA time zone, validated by the backend.
`business.deleted_at`	`string \| null`	System-managed UTC soft-deletion instant; null for active records.Format: date-time
`business.deleted_by`	`string \| null`	Deletion actor retained for history.Format: uuid

driver fields

Field	Type	Description & constraints
`driver.id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`driver.name`Required	`string`	Human-readable name shown in the workspace.
`driver.email`Required	`string`	Account email address.Format: email
`driver.active`	`boolean`	Whether this account or integration is enabled.
`driver.duty_status`	`online \| offline`	Resource-specific value; see the related workflow and schema.
`driver.location`	`object \| null`	Service or record location, using latitude/longitude in decimal degrees.
`driver.duty_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`driver.activation_code`	`string`	Returned once during provisioning/reset; administrator delivers it to driver.Response only

plans[] fields

Field	Type	Description & constraints
`plans.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`plans.vehicle_id`Required	`string`	Assigned or selected vehicle ID in this business.
`plans.driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`plans.revision`Required	`integer`	Current version used to detect stale edits or publication.
`plans.state`Required	`planning \| published \| superseded`	Planning/published version state or event visibility state.
`plans.start_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`plans.end_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`plans.stops`Required	`array<object>`	Ordered planned route stops.
`plans.return_leg`	`object`	Resource-specific value; see the related workflow and schema.
`plans.warnings`	`array<string>`	Constraint warnings requiring review where applicable.
`plans.unplanned_order_ids`	`array<string>`	Resource-specific value; see the related workflow and schema.
`plans.published`	`object \| null`	Resource-specific value; see the related workflow and schema.
`plans.received_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

orders[] fields

Field	Type	Description & constraints
`orders.id`	`string`	Optional on creation; generated if absent. Unique within authorized business; duplicates409 even if payload matches.Max length: 120
`orders.type`	`task \| break`	Record or field type; choose one of the listed values.
`orders.location`Required	`object`	Service or record location, using latitude/longitude in decimal degrees.
`orders.duration_seconds`Required	`integer`	Time needed to do the work, excluding travel, in seconds.Min: 1
`orders.window_start`Required	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`orders.window_end`Required	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`orders.status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled`	Live execution status. Administrator changes become pending_status until publication.
`orders.pending_status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled \| null`	Resource-specific value; see the related workflow and schema.
`orders.scheduled_at`	`string \| null`	Planned service-start instant; absence indicates unplanned work.
`orders.vehicle_id`	`string \| null`	Assigned or selected vehicle ID in this business.
`orders.driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`orders.replacement_driver_id`	`string \| null`	Administrator-selected replacement driver for a handover break.
`orders.custom_fields`	`object`	Values keyed by the business-defined custom field IDs. Existing orders retain their schema version.
`orders.schema_snapshot`	`object`	Immutable field definition/type/permission version for this order.Response only
`orders.actual_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`orders.actual_completed_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

orders.location fields

Field	Type	Description & constraints
`orders.location.latitude`Required	`number`	Latitude in decimal degrees, from -90 to 90.Min: -90 · Max: 90
`orders.location.longitude`Required	`number`	Longitude in decimal degrees, from -180 to 180.Min: -180 · Max: 180

evidence_requirements fields

Field	Type	Description & constraints
`evidence_requirements.require_photos`	`boolean`	Resource-specific value; see the related workflow and schema.
`evidence_requirements.require_signature`	`boolean`	Resource-specific value; see the related workflow and schema.

Example DriverSnapshot

{
  "business": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example Services",
    "time_zone": "Europe/Warsaw",
    "deleted_at": "2026-11-02T09:00:00Z",
    "deleted_by": "11111111-1111-4111-8111-111111111111"
  },
  "driver": {
    "id": "example-id",
    "name": "Example Services",
    "email": "dispatcher@example.com",
    "active": true,
    "duty_status": "online",
    "location": {
      "latitude": 52.2297,
      "longitude": 21.0122
    },
    "duty_started_at": "2026-11-02T09:00:00Z",
    "activation_code": "example"
  },
  "plans": [
    {
      "id": "example-id",
      "vehicle_id": "van-01",
      "driver_id": "driver-01",
      "revision": 1,
      "state": "planning",
      "start_at": "2026-11-02T08:00:00Z",
      "end_at": "2026-11-02T16:00:00Z",
      "stops": [
        {}
      ],
      "return_leg": {},
      "warnings": [
        "example"
      ],
      "unplanned_order_ids": [
        "example"
      ],
      "published": {},
      "received_at": "2026-11-02T09:00:00Z"
    }
  ],
  "orders": [
    {
      "id": "example-id",
      "type": "task",
      "location": {
        "latitude": 52.2297,
        "longitude": 21.0122
      },
      "duration_seconds": 1800,
      "window_start": "2026-11-02T09:00:00Z",
      "window_end": "2026-11-02T12:00:00Z",
      "status": "created",
      "pending_status": "created",
      "scheduled_at": "2026-11-02T09:30:00Z",
      "vehicle_id": "van-01",
      "driver_id": "driver-01",
      "replacement_driver_id": "example",
      "custom_fields": {},
      "schema_snapshot": {},
      "actual_started_at": "2026-11-02T09:00:00Z",
      "actual_completed_at": "2026-11-02T09:00:00Z"
    }
  ],
  "evidence_requirements": {
    "require_photos": false,
    "require_signature": false
  },
  "last_refreshed_at": "2026-11-02T09:00:00Z",
  "warnings": [
    "example"
  ]
}

Full schema

{
  "type": "object",
  "required": [
    "business",
    "driver",
    "plans",
    "orders",
    "last_refreshed_at"
  ],
  "properties": {
    "business": {
      "$ref": "#/components/schemas/Business"
    },
    "driver": {
      "$ref": "#/components/schemas/Driver"
    },
    "plans": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Plan"
      }
    },
    "orders": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Order"
      }
    },
    "evidence_requirements": {
      "type": "object",
      "required": [],
      "properties": {
        "require_photos": {
          "type": "boolean"
        },
        "require_signature": {
          "type": "boolean"
        }
      }
    },
    "last_refreshed_at": {
      "type": "string",
      "format": "date-time"
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}