Work orders: Work orders

Base URL: $BUSINESS_API

List field operations work orders

Logs

GET /work-orders

Lists the tenant's work orders with cursor pagination (limit defaults to 20, maximum 100; pass next_cursor as after). Filters for order type, priority, status, service area, crew, account and connection combine with AND, and q searches the order text and also matches orders of accounts whose holder matches the search. Requires operations read access.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

account_idstring · query · optional

Only orders raised for this account

connection_idstring · query · optional

Only orders raised for this connection

Returns

200 Work orders

Show attributes
dataarray of WorkOrder · required
Show child attributes
idstring · optional
tenant_idstring · optional
order_numberstring · optional
order_typestring · optional
prioritystring · optional
statusstring · optional
account_idstring · optional
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

connection_idstring · optional
connection_holder_namestring · optional

Display name of the customer who holds the referenced connection. Omitted when unknown.

descriptionstring · optional
has_moreboolean · required
next_cursorstring · optional

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

curl -X GET "$BUSINESS_API/work-orders" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "order_number": "ORD-2026-000142",
      "order_type": "order type",
      "priority": "priority",
      "status": "active",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
      "connection_holder_name": "Ana Matsinhe",
      "description": "Leitura confirmada no local."
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a field work order

Logs

POST /work-orders

Create a field work order, with its material lines from a kit or one by one

Materials are planned when the order is created (RFC 0071 section 5.3). kit_id fills the lines from a kit (default picks the kit set for the order type); materials add catalogue items or free-text parts, or adjust a kit line (quantity 0 removes it). Meters are required lines by default on installation and replacement orders. Lines are reserved at the natural source (the crew's van, the service area's warehouse, the main warehouse); a shortage is a warning in the response, never a refusal. Without materials, proposed_kit_id offers the order type's default kit.

Body application/json

order_typestring · required
prioritystring · optional
asset_idstring · optional
service_area_idstring · optional
account_idstring · optional
crew_idstring · optional
descriptionstring · required
scheduled_atstring (date-time) · optional
connection_idstring · optional
required_skillstring · optional
kit_idstring · optional

A kit (kit_), or default for the order type's default kit

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 Work order created, with each material line's availability and reservation

Show attributes
idstring · required
tenant_idstring · required
order_numberstring · required
order_typestring · required
prioritystring · required
statusstring · required
crew_idstring · optional
service_area_idstring · optional
connection_idstring · optional
connection_holder_namestring · optional

Display name of the customer who holds the referenced connection. Omitted when unknown.

descriptionstring · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
material_linesarray of WorkOrderMaterialLine · optional
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
material_cost_minorinteger (int64) · optional

Cost of the materials used, at average cost; per new connection on its installation order

proposed_kit_idstring · optional

Default kit for the order type, offered when created without materials

Errors 400 · 403

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

curl -X POST "$BUSINESS_API/work-orders" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "order_type": "order type",
  "priority": "priority",
  "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "description": "Leitura confirmada no local.",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "required_skill": "required skill",
  "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
{
  "id": "wor_2oUz9aQ9Pk2Rnyu1nAG9ZoClFso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "order_number": "ORD-2026-000142",
  "order_type": "order type",
  "priority": "priority",
  "status": "active",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z",
  "material_lines": [
    {
      "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"
    }
  ],
  "material_cost_minor": 1,
  "proposed_kit_id": "pro_2xh4kVlEItn0iXlimBdSi5r4MzJ"
}

Get work order details

Logs

GET /work-orders/{id}

Get work order details, with material lines and material cost

Returns one work order with its status, crew, schedule, execution details and its material lines. Responds 404 when the order is not in the caller's tenant. Requires operations read access.

Parameters

idstring · path · required

ID of the work order in the caller's tenant.

Returns

200 Work order details; material_lines and material_cost_minor appear when the order has materials

Show attributes
idstring · required
tenant_idstring · required
order_numberstring · required
order_typestring · required
prioritystring · required
statusstring · required
crew_idstring · optional
service_area_idstring · optional
connection_idstring · optional
connection_holder_namestring · optional

Display name of the customer who holds the referenced connection. Omitted when unknown.

descriptionstring · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
material_linesarray of WorkOrderMaterialLine · optional
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
material_cost_minorinteger (int64) · optional

Cost of the materials used, at average cost; per new connection on its installation order

proposed_kit_idstring · optional

Default kit for the order type, offered when created without materials

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

curl -X GET "$BUSINESS_API/work-orders/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "wor_2oUz9aQ9Pk2Rnyu1nAG9ZoClFso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "order_number": "ORD-2026-000142",
  "order_type": "order type",
  "priority": "priority",
  "status": "active",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z",
  "material_lines": [
    {
      "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"
    }
  ],
  "material_cost_minor": 1,
  "proposed_kit_id": "pro_2xh4kVlEItn0iXlimBdSi5r4MzJ"
}