Work orders: Actions

Base URL: $BUSINESS_API

Assign work order to crew

Logs

POST /work-orders/{id}/assign

Assigns a crew to a general work order, moves it to assigned and records the status change in its history; when the crew changes, reserved materials move to the new crew. Reassigning an already assigned order only changes the crew. Connection field orders (disconnection, reconnection, new installation, meter exchange) must use dispatch instead and get 409, as does any status that cannot move to assigned. Requires operations write access.

Parameters

idstring · path · required

ID of the work order to assign; it must not be a connection field order.

Returns

200 Work order assigned

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/assign" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Work order assigned

Complete work order

Logs

POST /work-orders/{id}/complete

Marks a general work order completed, stores the optional notes as its resolution notes, sets completed_at and records the status change in its history. Connection field orders must use execute instead and get 409, and so does an order whose current status cannot move to completed. Requires operations write access.

Parameters

idstring · path · required

ID of the work order to complete; it must not be a connection field order.

Returns

200 Work order completed

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/complete" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Work order completed

Get the metadata of a work order

Logs

GET /work-orders/{id}/metadata

Returns the custom key-value metadata attached to a work order, as resource_type work_order, the resource ID and a metadata map of strings. The work order must exist in the caller's tenant, otherwise 404. Requires business metadata read access.

Parameters

idstring · path · required

ID of the work order whose metadata is read.

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/work-orders/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /work-orders/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the given keys into the work order's metadata and returns the full resulting map; keys not mentioned are kept, and a key sent with an empty string value is deleted. Keys are at most 40 characters without square brackets or control characters, values at most 500 characters, and a resource may hold at most 50 keys; violations return 400 with per-key details. The work order must exist in the tenant (404 otherwise). Requires business metadata write access.

Parameters

idstring · path · required

ID of the work order whose metadata is merged.

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/work-orders/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

A work order's status log, newest first

Logs

GET /work-orders/{id}/status-history

Requires operations:read.

Parameters

idstring · path · required

Work order identifier

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Status changes

Show attributes
dataarray of WorkOrderStatusChange · optional
Show child attributes
idstring · optional
tenant_idstring · optional
work_order_idstring · optional
from_statusstring · optional

Absent on the entry that created the order

to_statusstring · optional
actor_idstring · optional
notestring · optional
note_codestring · optional

Stable code of a note the server wrote (work_order.generated, work_order.dispatched, work_order.cancel.settled_before_cutoff, work_order.cancel.payment_reversed); clients word it and fall back to note. Absent for notes people typed.

note_paramsobject · optional

Values the note code fills in: source for work_order.generated, crew for work_order.dispatched.

changed_atstring (date-time) · optional
has_moreboolean · optional
next_cursorstring · optional

Permissions operations:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/work-orders/{id}/status-history" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "wor_2I0lP26zrs8XRIe5nuwXV2uhJE0",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "from_status": "from status",
      "to_status": "to status",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "note": "Leitura confirmada no local.",
      "note_code": "NOT-2026-000142",
      "note_params": {
        "key": "value"
      },
      "changed_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Dispatch a connection field order to a skilled crew

Logs

POST /work-orders/{id}/dispatch

Sends a connection field order to a crew and moves it to dispatched, optionally with a scheduled_for time; give crew_id or set auto_assign to pick the best crew with the required skill. The order must be a field order (400 otherwise), and a crew lacking the required skill, a status that cannot be dispatched, or missing materials for required lines returns 409. A work_order.dispatched event is emitted and the change is recorded in the status history. Requires operations write access.

Parameters

idstring · path · required

ID of the connection field order to dispatch.

Body application/json

crew_idstring · optional
auto_assignboolean · optional
scheduled_forstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/dispatch" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "auto_assign": true,
  "scheduled_for": "scheduled for"
}'
Response 200

Success

Record a field order outcome

Logs

POST /work-orders/{id}/execute

Record a field order outcome: completed or failed_access_denied

Records the field outcome of a connection field order: result completed or failed_access_denied, with optional executed_at (defaults to now), final reading and notes. Completing a disconnection requires applied_seal_serial and evidence_photo, and a failed_access_denied result requires notes. A work_order.executed event is emitted for downstream processing such as connection status changes; a status that cannot take the result returns 409, and a non-field order returns 400. Requires operations write access.

Parameters

idstring · path · required

ID of the connection field order whose outcome is recorded.

Body application/json

resultstring · optional
executed_atstring · optional
applied_seal_serialstring · optional
evidence_photostring · optional
final_readingstring · optional
notesstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/execute" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "result": "result",
  "executed_at": "2026-11-19T09:30:00Z",
  "applied_seal_serial": "applied seal serial",
  "evidence_photo": "evidence photo",
  "final_reading": "final reading",
  "notes": "Leitura confirmada no local."
}'
Response 200

Success

Cancel a work order that is not completed

Logs

POST /work-orders/{id}/cancel

Cancelling publishes the status change; inventory releases the order's reservations and takes back anything issued to it. Cancelling a cancelled order changes nothing.

Parameters

idstring · path · required

Work order ID (wko_)

Body application/json

reasonstring · required

Returns

200 Work order cancelled

Errors 400 · 401 · 403 · 404 · 409

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/cancel" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200

Work order cancelled

Get work order material lines

Logs

GET /work-orders/{id}/material-lines

A work order's material lines with availability, reservations, issues, returns and cost

Catalogue lines carry the inventory picture; free-text lines are flagged needs_mapping and touch no stock. Free-text materials recorded before material lines are listed read-only with legacy true.

Parameters

idstring · path · required

Work order ID (wko_)

Returns

200 Material lines

Show attributes
dataarray of WorkOrderMaterialLine · required
Show child attributes
idstring · required

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · required
work_order_idstring · required
item_idstring · optional
item_codestring · optional
part_codestring · optional
descriptionstring · optional
unitstring · optional
plannednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required
source_location_idstring · optional
kit_idstring · optional
needs_mappingboolean · required

Free text for a stores person to map; touches no stock

legacyboolean · optional
stock_statusstring · required

one of reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · optional
is_meterboolean · optional
cost_minorinteger (int64) · required

Issues less returns at average cost

availabilityobject · optional
Show child attributes
source_location_idstring · optional
source_location_namestring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · optional
Show child attributes
location_idstring · optional
location_namestring · optional
kindstring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · optional
Show child attributes
idstring · optional
location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · optional
statusstring · optional
expires_atstring (date-time) · optional
created_atstring (date-time) · optional
suggested_transferobject · optional
Show child attributes
from_location_idstring · optional
to_location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404

Permissions operations:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/work-orders/{id}/material-lines" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "item_code": "ITE-2026-000142",
      "part_code": "PAR-2026-000142",
      "description": "Leitura confirmada no local.",
      "unit": "unit",
      "planned": 1,
      "reserved": 1,
      "issued": 1,
      "used": 1,
      "returned": 1,
      "required": true,
      "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
      "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
      "needs_mapping": true,
      "legacy": true,
      "stock_status": "reserved",
      "serialised": true,
      "is_meter": true,
      "cost_minor": 1,
      "availability": {
        "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
        "source_location_name": "Ana Matsinhe",
        "available": 1,
        "short": 1,
        "other_locations": [
          {
            "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
            "location_name": "Ana Matsinhe",
            "kind": "active",
            "available": 1
          }
        ]
      },
      "reservations": [
        {
          "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
          "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
          "quantity": 1,
          "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
          "status": "active",
          "expires_at": "2026-11-19T09:30:00Z",
          "created_at": "2026-11-19T09:30:00Z"
        }
      ],
      "suggested_transfer": {
        "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
        "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
        "quantity": 1
      },
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Add work order material lines

Logs

POST /work-orders/{id}/material-lines

Add material lines from a kit or one by one, until the order ends

Adds planned material lines to a work order from a kit (kit_id, or default for the order type's default kit) or from an explicit materials list, and returns 201 with the new lines in a data array. Items already on the order are skipped, and if nothing new remains the request fails with 409; a completed or cancelled order also returns 409. Catalogue items are reserved in inventory when inventory is available. Requires operations write access.

Parameters

idstring · path · required

Work order ID (wko_)

Body application/json

kit_idstring · optional
materialsarray of WorkOrderMaterialInput · optional
Show child attributes
item_idstring · optional

Catalogue item; omit for a free-text part

part_codestring · optional
descriptionstring · optional
quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

unitstring · optional
requiredboolean · optional

Blocks dispatch until reserved; defaults to true for meters on installation and replacement orders

source_location_idstring · optional

Returns

201 Lines added and reserved where the stock is

Show attributes
dataarray of WorkOrderMaterialLine · required
Show child attributes
idstring · required

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · required
work_order_idstring · required
item_idstring · optional
item_codestring · optional
part_codestring · optional
descriptionstring · optional
unitstring · optional
plannednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required
source_location_idstring · optional
kit_idstring · optional
needs_mappingboolean · required

Free text for a stores person to map; touches no stock

legacyboolean · optional
stock_statusstring · required

one of reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · optional
is_meterboolean · optional
cost_minorinteger (int64) · required

Issues less returns at average cost

availabilityobject · optional
Show child attributes
source_location_idstring · optional
source_location_namestring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · optional
Show child attributes
location_idstring · optional
location_namestring · optional
kindstring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · optional
Show child attributes
idstring · optional
location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · optional
statusstring · optional
expires_atstring (date-time) · optional
created_atstring (date-time) · optional
suggested_transferobject · optional
Show child attributes
from_location_idstring · optional
to_location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/material-lines" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "materials": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "part_code": "PAR-2026-000142",
      "description": "Leitura confirmada no local.",
      "quantity": 1,
      "unit": "unit",
      "required": true,
      "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd"
    }
  ]
}'
Response 201
{
  "data": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "item_code": "ITE-2026-000142",
      "part_code": "PAR-2026-000142",
      "description": "Leitura confirmada no local.",
      "unit": "unit",
      "planned": 1,
      "reserved": 1,
      "issued": 1,
      "used": 1,
      "returned": 1,
      "required": true,
      "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
      "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
      "needs_mapping": true,
      "legacy": true,
      "stock_status": "reserved",
      "serialised": true,
      "is_meter": true,
      "cost_minor": 1,
      "availability": {
        "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
        "source_location_name": "Ana Matsinhe",
        "available": 1,
        "short": 1,
        "other_locations": [
          {
            "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
            "location_name": "Ana Matsinhe",
            "kind": "active",
            "available": 1
          }
        ]
      },
      "reservations": [
        {
          "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
          "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
          "quantity": 1,
          "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
          "status": "active",
          "expires_at": "2026-11-19T09:30:00Z",
          "created_at": "2026-11-19T09:30:00Z"
        }
      ],
      "suggested_transfer": {
        "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
        "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
        "quantity": 1
      },
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Change a line until its material is issued

Logs

PATCH /work-orders/{id}/material-lines/{line}

Change a line until its material is issued; an item_id maps a free-text line to the catalogue

Changes a material line that has not been issued yet: planned quantity (must be positive), required flag, source location, description (up to 255 characters), or item_id to map a free-text line to a catalogue item. Returns the updated line with its stock picture and syncs inventory reservations. A completed or cancelled order, a line with issued material, remapping a line that already has an item, or an item already on the order returns 409. Requires operations write access.

Parameters

idstring · path · required

Work order ID (wko_)

linestring · path · required

Material line ID (wml_)

Body application/json

item_idstring · optional

Maps a free-text line to a catalogue item

quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · optional
source_location_idstring · optional
descriptionstring · optional

Returns

200 Line changed and its reservation adjusted

Show attributes
idstring · required

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · required
work_order_idstring · required
item_idstring · optional
item_codestring · optional
part_codestring · optional
descriptionstring · optional
unitstring · optional
plannednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required
source_location_idstring · optional
kit_idstring · optional
needs_mappingboolean · required

Free text for a stores person to map; touches no stock

legacyboolean · optional
stock_statusstring · required

one of reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · optional
is_meterboolean · optional
cost_minorinteger (int64) · required

Issues less returns at average cost

availabilityobject · optional
Show child attributes
source_location_idstring · optional
source_location_namestring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · optional
Show child attributes
location_idstring · optional
location_namestring · optional
kindstring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · optional
Show child attributes
idstring · optional
location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · optional
statusstring · optional
expires_atstring (date-time) · optional
created_atstring (date-time) · optional
suggested_transferobject · optional
Show child attributes
from_location_idstring · optional
to_location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X PATCH "$BUSINESS_API/work-orders/{id}/material-lines/{line}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "quantity": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "description": "Leitura confirmada no local."
}'
Response 200
{
  "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "item_code": "ITE-2026-000142",
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "unit": "unit",
  "planned": 1,
  "reserved": 1,
  "issued": 1,
  "used": 1,
  "returned": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "needs_mapping": true,
  "legacy": true,
  "stock_status": "reserved",
  "serialised": true,
  "is_meter": true,
  "cost_minor": 1,
  "availability": {
    "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
    "source_location_name": "Ana Matsinhe",
    "available": 1,
    "short": 1,
    "other_locations": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "location_name": "Ana Matsinhe",
        "kind": "active",
        "available": 1
      }
    ]
  },
  "reservations": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "status": "active",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "suggested_transfer": {
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "quantity": 1
  },
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Remove a line until its material is issued

Logs

DELETE /work-orders/{id}/material-lines/{line}

Remove a line until its material is issued; its reservations are released

Removes a planned material line from a work order and returns 204; inventory reservations are resynced for catalogue items. A line with material already issued, or an order that is completed or cancelled, returns 409. Requires operations write access.

Parameters

idstring · path · required

Work order ID (wko_)

linestring · path · required

Material line ID (wml_)

Returns

204 Line removed

Errors 400 · 401 · 403 · 404 · 409

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X DELETE "$BUSINESS_API/work-orders/{id}/material-lines/{line}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Line removed

Issue work order material line

Logs

POST /work-orders/{id}/material-lines/{line}/issue

Record material issued to a line, for crews working out of order or offline

A held reservation at the location is consumed, so reserved and issued never count the same units. The location defaults to the line's reservation, then its source. Meters are issued when installed through the meter actions. Replaying the Idempotency-Key records once.

Parameters

idstring · path · required

Work order ID (wko_)

linestring · path · required

Material line ID (wml_)

Idempotency-Keystring · header · optional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Body application/json

quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

location_idstring · optional
serialsarray of string · optional
reasonstring · optional
occurred_atstring (date-time) · optional

Returns

200 Replayed Idempotency-Key; nothing recorded twice

Show attributes
idstring · required

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · required
work_order_idstring · required
item_idstring · optional
item_codestring · optional
part_codestring · optional
descriptionstring · optional
unitstring · optional
plannednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required
source_location_idstring · optional
kit_idstring · optional
needs_mappingboolean · required

Free text for a stores person to map; touches no stock

legacyboolean · optional
stock_statusstring · required

one of reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · optional
is_meterboolean · optional
cost_minorinteger (int64) · required

Issues less returns at average cost

availabilityobject · optional
Show child attributes
source_location_idstring · optional
source_location_namestring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · optional
Show child attributes
location_idstring · optional
location_namestring · optional
kindstring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · optional
Show child attributes
idstring · optional
location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · optional
statusstring · optional
expires_atstring (date-time) · optional
created_atstring (date-time) · optional
suggested_transferobject · optional
Show child attributes
from_location_idstring · optional
to_location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409

Permissions operations:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X POST "$BUSINESS_API/work-orders/{id}/material-lines/{line}/issue" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 1,
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "serials": [
    "serial"
  ],
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z"
}'
Response 200
{
  "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "item_code": "ITE-2026-000142",
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "unit": "unit",
  "planned": 1,
  "reserved": 1,
  "issued": 1,
  "used": 1,
  "returned": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "needs_mapping": true,
  "legacy": true,
  "stock_status": "reserved",
  "serialised": true,
  "is_meter": true,
  "cost_minor": 1,
  "availability": {
    "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
    "source_location_name": "Ana Matsinhe",
    "available": 1,
    "short": 1,
    "other_locations": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "location_name": "Ana Matsinhe",
        "kind": "active",
        "available": 1
      }
    ]
  },
  "reservations": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "status": "active",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "suggested_transfer": {
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "quantity": 1
  },
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Record work order material use

Logs

POST /work-orders/{id}/material-lines/{line}/use

Record the quantity a line actually used, which may differ from planned

Setting the same quantity again changes nothing, so an offline phone can replay it. On a completed order inventory settles the difference: unused issued stock returns to the van or warehouse, and extra use is issued from the van.

Parameters

idstring · path · required

Work order ID (wko_)

linestring · path · required

Material line ID (wml_)

Body application/json

usednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

occurred_atstring (date-time) · optional

Returns

200 Use recorded

Show attributes
idstring · required

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · required
work_order_idstring · required
item_idstring · optional
item_codestring · optional
part_codestring · optional
descriptionstring · optional
unitstring · optional
plannednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required
source_location_idstring · optional
kit_idstring · optional
needs_mappingboolean · required

Free text for a stores person to map; touches no stock

legacyboolean · optional
stock_statusstring · required

one of reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · optional
is_meterboolean · optional
cost_minorinteger (int64) · required

Issues less returns at average cost

availabilityobject · optional
Show child attributes
source_location_idstring · optional
source_location_namestring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · optional
Show child attributes
location_idstring · optional
location_namestring · optional
kindstring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · optional
Show child attributes
idstring · optional
location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · optional
statusstring · optional
expires_atstring (date-time) · optional
created_atstring (date-time) · optional
suggested_transferobject · optional
Show child attributes
from_location_idstring · optional
to_location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409

Permissions operations:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X POST "$BUSINESS_API/work-orders/{id}/material-lines/{line}/use" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "used": 1,
  "occurred_at": "2026-11-19T09:30:00Z"
}'
Response 200
{
  "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "item_code": "ITE-2026-000142",
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "unit": "unit",
  "planned": 1,
  "reserved": 1,
  "issued": 1,
  "used": 1,
  "returned": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "needs_mapping": true,
  "legacy": true,
  "stock_status": "reserved",
  "serialised": true,
  "is_meter": true,
  "cost_minor": 1,
  "availability": {
    "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
    "source_location_name": "Ana Matsinhe",
    "available": 1,
    "short": 1,
    "other_locations": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "location_name": "Ana Matsinhe",
        "kind": "active",
        "available": 1
      }
    ]
  },
  "reservations": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "status": "active",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "suggested_transfer": {
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "quantity": 1
  },
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Record unused material brought back from a line

Logs

POST /work-orders/{id}/material-lines/{line}/return

Returns issued material from a work order line to stock (quantity, optional location_id, serials, reason and occurred_at) and responds 201 with the updated line. Send an Idempotency-Key header (1 to 255 visible ASCII characters) to make retries safe: a replay returns 200 with Idempotent-Replayed: true. Free-text lines, unavailable inventory, or returning below a quantity already recorded as used on a completed order return 409.

Parameters

idstring · path · required

Work order ID (wko_)

linestring · path · required

Material line ID (wml_)

Idempotency-Keystring · header · optional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Body application/json

quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

location_idstring · optional
serialsarray of string · optional
reasonstring · optional
occurred_atstring (date-time) · optional

Returns

200 Replayed Idempotency-Key; nothing recorded twice

Show attributes
idstring · required

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · required
work_order_idstring · required
item_idstring · optional
item_codestring · optional
part_codestring · optional
descriptionstring · optional
unitstring · optional
plannednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required
source_location_idstring · optional
kit_idstring · optional
needs_mappingboolean · required

Free text for a stores person to map; touches no stock

legacyboolean · optional
stock_statusstring · required

one of reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · optional
is_meterboolean · optional
cost_minorinteger (int64) · required

Issues less returns at average cost

availabilityobject · optional
Show child attributes
source_location_idstring · optional
source_location_namestring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · optional
Show child attributes
location_idstring · optional
location_namestring · optional
kindstring · optional
availablenumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · optional
Show child attributes
idstring · optional
location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · optional
statusstring · optional
expires_atstring (date-time) · optional
created_atstring (date-time) · optional
suggested_transferobject · optional
Show child attributes
from_location_idstring · optional
to_location_idstring · optional
quantitynumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409

Permissions operations:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X POST "$BUSINESS_API/work-orders/{id}/material-lines/{line}/return" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 1,
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "serials": [
    "serial"
  ],
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z"
}'
Response 200
{
  "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "item_code": "ITE-2026-000142",
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "unit": "unit",
  "planned": 1,
  "reserved": 1,
  "issued": 1,
  "used": 1,
  "returned": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "needs_mapping": true,
  "legacy": true,
  "stock_status": "reserved",
  "serialised": true,
  "is_meter": true,
  "cost_minor": 1,
  "availability": {
    "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
    "source_location_name": "Ana Matsinhe",
    "available": 1,
    "short": 1,
    "other_locations": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "location_name": "Ana Matsinhe",
        "kind": "active",
        "available": 1
      }
    ]
  },
  "reservations": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "status": "active",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "suggested_transfer": {
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "quantity": 1
  },
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List a field order bill of materials

Logs

GET /work-orders/{id}/materials

Lists the simple material records (part code, description, quantity, unit) logged against a work order, oldest first, with cursor pagination (limit defaults to 20, maximum 100) and a total_count. These are separate from inventory-backed material lines. Responds 404 when the work order does not exist and requires operations read access.

Parameters

idstring · path · required

ID of the work order whose material records are listed.

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions operations:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/work-orders/{id}/materials" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Add a part to the bill of materials

Logs

POST /work-orders/{id}/materials

Logs a material used on a work order as a simple record and returns 201; part_code and a positive quantity are required, description and unit are optional. The record does not touch inventory stock, unlike material lines. Responds 404 when the work order does not exist and requires operations write access.

Parameters

idstring · path · required

ID of the work order the material is logged against.

Body application/json

part_codestring · optional
descriptionstring · optional
quantityinteger · optional
unitstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions operations:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/materials" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "quantity": 1,
  "unit": "unit"
}'
Response 200

Success