Work Requests API

Read work requests from Scan2Evolve and update them from your CMMS with status changes, root cause, resolution, and closure details.

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-requests`	List work requests (paginated, filterable)
`GET`	`/api/v1/work-requests/{id}`	Get a single work request with linked tasks
`POST`	`/api/downstream/work-requests/{id}/sync`	Update a work request — status, root cause, resolution, closure note

List work requests

Retrieve all work requests for the authenticated organization. Returns paginated results.

Request

GET /api/v1/work-requests 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

{
  "workRequests": [
    {
      "id": "wr_abc123",
      "title": "Pump A vibration exceeds threshold",
      "description": "Vibration reading 12.5 mm/s (threshold: 8.0). Needs inspection.",
      "priority": "HIGH",
      "status": "COMPLETED",
      "location": "Building 3, Level 2",
      "assetId": "asset_456",
      "assetName": "Centrifugal Pump A",
      "dueDate": "2026-03-15T00:00:00.000Z",
      "requestedBy": {
        "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-WR-78432",
      "externalStatus": "Closed",
      "externalUrl": "https://cmms.example.com/work-requests/78432",
      "syncStatus": "SYNCED",
      "lastSyncedAt": "2026-03-10T14:30:00.000Z",
      "rootCause": "Equipment Failure",
      "resolution": "Replaced faulty bearing and realigned shaft",
      "closureNote": "Verified pump operating within spec after repair",
      "createdAt": "2026-03-08T09:15:00.000Z",
      "updatedAt": "2026-03-10T14:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Query parameters

status — NEW | IN_PROGRESS | IN_REVIEW | 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-requests?status=COMPLETED&priority=HIGH&limit=20 HTTP/1.1
Host: api.scan2evolve.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Get a work request

Retrieve a single work request by ID, including linked tasks and closure details. Returns 404 if not found or belongs to another organization.

Request

GET /api/v1/work-requests/wr_abc123 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": "wr_abc123",
  "title": "Pump A vibration exceeds threshold",
  "description": "Vibration reading 12.5 mm/s (threshold: 8.0). Needs inspection.",
  "priority": "HIGH",
  "status": "COMPLETED",
  "location": "Building 3, Level 2",
  "assetId": "asset_456",
  "assetName": "Centrifugal Pump A",
  "dueDate": "2026-03-15T00:00:00.000Z",
  "requestedBy": { "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-WR-78432",
  "externalStatus": "Closed",
  "externalUrl": "https://cmms.example.com/work-requests/78432",
  "syncStatus": "SYNCED",
  "lastSyncedAt": "2026-03-10T14:30: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": "Replace bearing on Pump A",
      "status": "COMPLETED",
      "assignedTo": { "id": "usr_002", "name": "John Smith" },
      "completionNote": "Bearing replaced, shaft realigned, test run passed",
      "createdAt": "2026-03-09T08:00:00.000Z",
      "completedAt": "2026-03-10T13:45:00.000Z"
    }
  ],
  "createdAt": "2026-03-08T09:15:00.000Z",
  "updatedAt": "2026-03-10T14:30:00.000Z"
}

Get by ID includes tasks

The single work request response includes linked tasks (if any). The list endpoint does not include tasks to keep responses small.

Update a work request

Push status changes, root cause, resolution, and closure details 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 Request 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	`NEW` \| `IN_PROGRESS` \| `IN_REVIEW` \| `COMPLETED` \| `CANCELLED`
`externalStatus`	string	No	Status label as it appears in your CMMS (free-text)
`externalUrl`	string (URL)	No	Deep link to this work request 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

Request

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

{
  "externalId": "CMMS-WR-78432",
  "status": "COMPLETED",
  "externalStatus": "Closed",
  "externalUrl": "https://cmms.example.com/work-requests/78432",
  "rootCause": "Equipment Failure",
  "resolution": "Replaced faulty bearing and realigned shaft",
  "closureNote": "Verified pump operating within spec after repair"
}

Response (200)

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

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

Response fields (GET)

id — Scan2Evolve work request ID
title, description — work request details
priority — LOW | MEDIUM | HIGH | CRITICAL
status — NEW | IN_PROGRESS | IN_REVIEW | COMPLETED | CANCELLED
requestedBy — user who raised the work request
assignedTo — user assigned to work on this request
assignedToGroup — group assigned
asset — related asset including its site
sourceInspection — inspection that generated this work request (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, and completion notes

Error responses

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