Work Orders API

Read work orders from Scan2Evolve and update them from your CMMS with status changes, root cause, resolution, closure details, completion time, and actual hours.

Authentication

GET endpoints (list, get by ID) use the same API key (Bearer or Basic auth) as other v1 APIs. See Authentication.

POST endpoint(update) uses a Bearer token + X-API-KEY configured in your organization's downstream integration settings (Admin → Settings → Downstream Integration).

Quick reference

Method	Path	Description
`GET`	`/api/v1/work-orders`	List work orders (paginated, filterable)
`GET`	`/api/v1/work-orders/{id}`	Get a single work order with linked tasks and time tracking
`POST`	`/api/downstream/work-orders/{id}/sync`	Update a work order — status, root cause, resolution, closure note, completion time, actual hours

List work orders

Retrieve all work orders for the authenticated organization. Returns paginated results with time tracking.

Request

GET /api/v1/work-orders HTTP/1.1
Host: api.scan2evolve.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "workOrders": [
    {
      "id": "wo_def456",
      "title": "Replace bearing on Pump A",
      "description": "Bearing failure detected during inspection. Replace and realign shaft.",
      "priority": "HIGH",
      "status": "COMPLETED",
      "location": "Building 3, Level 2",
      "assetId": "asset_456",
      "assetName": "Centrifugal Pump A",
      "estimatedHours": 6.0,
      "actualHours": 4.5,
      "dueDate": "2026-03-15T00:00:00.000Z",
      "startedAt": "2026-03-09T08:00:00.000Z",
      "completedAt": "2026-03-10T14:30:00.000Z",
      "createdBy": {
        "id": "usr_001",
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
      },
      "assignedTo": {
        "id": "usr_002",
        "name": "John Smith",
        "email": "john.smith@example.com"
      },
      "assignedToGroup": {
        "id": "grp_maint",
        "name": "Maintenance Team"
      },
      "asset": {
        "id": "asset_456",
        "name": "Centrifugal Pump A",
        "code": "PUMP-A-001",
        "site": {
          "id": "site_789",
          "name": "Melbourne Warehouse",
          "code": "MEL-WH"
        }
      },
      "sourceInspection": {
        "id": "ins_012",
        "inspectionNumber": "INS-2026-0042"
      },
      "externalId": "CMMS-WO-90215",
      "externalStatus": "Closed",
      "externalUrl": "https://cmms.example.com/work-orders/90215",
      "syncStatus": "SYNCED",
      "lastSyncedAt": "2026-03-10T15:00:00.000Z",
      "rootCause": "Equipment Failure",
      "resolution": "Replaced faulty bearing and realigned shaft",
      "closureNote": "Verified pump operating within spec after repair",
      "createdAt": "2026-03-08T09:30:00.000Z",
      "updatedAt": "2026-03-10T15:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 28,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Query parameters

status — DRAFT | ASSIGNED | IN_PROGRESS | ON_HOLD | COMPLETED | CANCELLED
priority — LOW | MEDIUM | HIGH | CRITICAL
siteId — filter by asset's site
assetId — filter by asset
syncStatus — PENDING | SYNCED | FAILED
limit — results per page (default 50, max 200)
offset — skip N results for pagination

Example with filters

GET /api/v1/work-orders?status=IN_PROGRESS&siteId=site_789&limit=20 HTTP/1.1
Host: api.scan2evolve.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Get a work order

Retrieve a single work order by ID, including time tracking, linked tasks (with per-task time tracking), and closure details. Returns 404 if not found or belongs to another organization.

Request

GET /api/v1/work-orders/wo_def456 HTTP/1.1
Host: api.scan2evolve.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "wo_def456",
  "title": "Replace bearing on Pump A",
  "description": "Bearing failure detected during inspection. Replace and realign shaft.",
  "priority": "HIGH",
  "status": "COMPLETED",
  "location": "Building 3, Level 2",
  "assetId": "asset_456",
  "assetName": "Centrifugal Pump A",
  "estimatedHours": 6.0,
  "actualHours": 4.5,
  "dueDate": "2026-03-15T00:00:00.000Z",
  "startedAt": "2026-03-09T08:00:00.000Z",
  "completedAt": "2026-03-10T14:30:00.000Z",
  "createdBy": { "id": "usr_001", "name": "Jane Doe", "email": "jane.doe@example.com" },
  "assignedTo": { "id": "usr_002", "name": "John Smith", "email": "john.smith@example.com" },
  "assignedToGroup": { "id": "grp_maint", "name": "Maintenance Team" },
  "asset": {
    "id": "asset_456", "name": "Centrifugal Pump A", "code": "PUMP-A-001",
    "site": { "id": "site_789", "name": "Melbourne Warehouse", "code": "MEL-WH" }
  },
  "sourceInspection": { "id": "ins_012", "inspectionNumber": "INS-2026-0042" },
  "externalId": "CMMS-WO-90215",
  "externalStatus": "Closed",
  "externalUrl": "https://cmms.example.com/work-orders/90215",
  "syncStatus": "SYNCED",
  "lastSyncedAt": "2026-03-10T15:00:00.000Z",
  "rootCause": "Equipment Failure",
  "resolution": "Replaced faulty bearing and realigned shaft",
  "closureNote": "Verified pump operating within spec after repair",
  "tasks": [
    {
      "id": "task_001",
      "taskNumber": "TSK-2026-0101",
      "title": "Remove old bearing",
      "status": "COMPLETED",
      "assignedTo": { "id": "usr_002", "name": "John Smith" },
      "estimatedHours": 2.0,
      "actualHours": 1.5,
      "completionNote": "Old bearing removed, housing cleaned",
      "createdAt": "2026-03-09T08:00:00.000Z",
      "startedAt": "2026-03-09T08:15:00.000Z",
      "completedAt": "2026-03-09T10:00:00.000Z"
    },
    {
      "id": "task_002",
      "taskNumber": "TSK-2026-0102",
      "title": "Install new bearing and realign shaft",
      "status": "COMPLETED",
      "assignedTo": { "id": "usr_002", "name": "John Smith" },
      "estimatedHours": 4.0,
      "actualHours": 3.0,
      "completionNote": "Bearing installed, shaft aligned, test run passed",
      "createdAt": "2026-03-09T10:00:00.000Z",
      "startedAt": "2026-03-09T10:30:00.000Z",
      "completedAt": "2026-03-10T13:45:00.000Z"
    }
  ],
  "createdAt": "2026-03-08T09:30:00.000Z",
  "updatedAt": "2026-03-10T15:00:00.000Z"
}

Get by ID includes tasks with time tracking

The single work order response includes linked tasks with per-task estimatedHours, actualHours, startedAt, completedAt. The list endpoint does not include tasks.

Update a work order

Push status changes, root cause, resolution, closure details, completion time, and actual hours from your CMMS back to Scan2Evolve. All fields are optional — send only what changed. You can call this endpoint multiple times; each call updates only the fields you include.

Prerequisites

1.Downstream integration must be configured and active (Admin → Settings → Downstream Integration).

2. Uses Bearer token + X-API-KEY from your downstream integration settings (different from the v1 API key used for GET endpoints above).

3. The Work Order id is included in the payload when Scan2Evolve originally pushes the item to your CMMS.

Request body fields

Field	Type	Required	Description
`externalId`	string	No	Your CMMS reference number / ticket ID
`status`	enum	No	`DRAFT` \| `ASSIGNED` \| `IN_PROGRESS` \| `ON_HOLD` \| `COMPLETED` \| `CANCELLED`
`externalStatus`	string	No	Status label as it appears in your CMMS (free-text)
`externalUrl`	string (URL)	No	Deep link to this work order in your CMMS
`rootCause`	string (max 500)	No	Root cause category or description
`resolution`	string (max 2000)	No	What was done to resolve the issue
`closureNote`	string (max 2000)	No	Additional closure notes or follow-up recommendations
`completedAt`	string (ISO 8601)	No	When the work was completed (e.g. `2026-03-10T14:30:00.000Z`)
`actualHours`	number	No	Actual hours spent (e.g. `4.5`)

Full closure example

POST /api/downstream/work-orders/{id}/sync
Authorization: Bearer <token>
X-API-KEY: <your_api_key>
Content-Type: application/json

{
  "externalId": "CMMS-WO-90215",
  "status": "COMPLETED",
  "externalStatus": "Closed",
  "externalUrl": "https://cmms.example.com/work-orders/90215",
  "rootCause": "Equipment Failure",
  "resolution": "Replaced faulty bearing and realigned shaft",
  "closureNote": "Verified pump operating within spec after repair",
  "completedAt": "2026-03-10T14:30:00.000Z",
  "actualHours": 4.5
}

Response (200)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Work order updated successfully"
}

Status-only update (work started)

POST /api/downstream/work-orders/{id}/sync
Authorization: Bearer <token>
X-API-KEY: <your_api_key>
Content-Type: application/json

{
  "status": "IN_PROGRESS",
  "externalId": "CMMS-WO-90215"
}

Incremental updates

Send status when work starts, then send rootCause, resolution, closureNote, completedAt, and actualHours when work finishes. Fields you omit are left unchanged.

Response fields (GET)

id — Scan2Evolve work order ID
title, description — work order details
priority — LOW | MEDIUM | HIGH | CRITICAL
status — DRAFT | ASSIGNED | IN_PROGRESS | ON_HOLD | COMPLETED | CANCELLED
estimatedHours — planned hours (decimal or null)
actualHours — actual hours spent (decimal or null)
startedAt — when work started (ISO 8601 or null)
completedAt — when work was completed (ISO 8601 or null)
createdBy — user who created the work order
assignedTo — user assigned to work on this order
assignedToGroup — group assigned
asset — related asset including its site
sourceInspection — inspection that generated this work order (null if manual)
externalId — your CMMS reference number
externalStatus — status as it appears in your CMMS
externalUrl — deep link to this item in your CMMS
syncStatus — PENDING | SYNCED | FAILED
rootCause — root cause label
resolution — resolution details
closureNote — additional closure notes
tasks — (Get by ID only) linked tasks with status, assignee, time tracking, and completion notes

Error responses

401 — Missing or invalid API key / token. 400 — Validation error (invalid status, URL, datetime, or hours value). 403 — Downstream integration not active (POST only). 404 — Work order not found. 429 — Rate limit exceeded. See Error Handling for details.