Reading assignments

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
round_idstring · required
reader_idstring · required
meter_idsarray of string · required
statusstring · required

one of assigned, in_progress, completed, cancelled

assigned_bystring · required
assigned_atstring (date-time) · required
due_atstring · optional · nullable
started_atstring · optional · nullable
completed_atstring · optional · nullable
cancelled_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "rea_2EipDoOH7eqBZSWv5EopbOSVrAi",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "round_id": "rou_2yOn3qm15M8hnMSBVgwddaODZOG",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "status": "assigned",
  "assigned_by": "assigned by",
  "assigned_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List field-reader assignments

Logs

GET /reading-assignments

Returns a cursor-paginated page of reading assignments, each giving the reader, the round and the meters that reader must read. Use limit (default 20, maximum 100) and after to page. Requires the business:reading-assignments:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

round_idstring · query · optional

Returns only assignments that belong to this reading round ID.

reader_idstring · query · optional

Returns only assignments given to this reader (the user ID of the meter reader).

statusstring · query · optional

Returns only assignments in this status: assigned, in_progress, completed or cancelled; any other value returns 400.

one of assigned, in_progress, completed, cancelled

Returns

200 Filtered reader assignments with meter stops

Permissions business:reading-assignments:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/reading-assignments" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Filtered reader assignments with meter stops

Assign route meters in a round to a utility reader

Logs

POST /reading-assignments

If meter_ids is omitted, all route meters not already assigned in this round are assigned.

Body application/json

round_idstring · required
reader_idstring · required
meter_idsarray of string · optional
due_atstring (date-time) · optional

Returns

201 Reading assignment created

Show attributes
idstring · required
tenant_idstring · required
round_idstring · required
reader_idstring · required
meter_idsarray of string · required
statusstring · required

one of assigned, in_progress, completed, cancelled

assigned_bystring · required
assigned_atstring (date-time) · required
due_atstring · optional · nullable
started_atstring · optional · nullable
completed_atstring · optional · nullable
cancelled_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions business:reading-assignments:create · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/reading-assignments" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "round_id": "rou_2yOn3qm15M8hnMSBVgwddaODZOG",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "due_at": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "id": "rea_2EipDoOH7eqBZSWv5EopbOSVrAi",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "round_id": "rou_2yOn3qm15M8hnMSBVgwddaODZOG",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "status": "assigned",
  "assigned_by": "assigned by",
  "assigned_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get a field-reader assignment

Logs

GET /reading-assignments/{id}

Returns one reading assignment with its reader, round, meter IDs, due date and the timestamps of each status change. An assignment that does not exist in the tenant returns 404. Requires the business:reading-assignments:read permission.

Parameters

idstring · path · required

ID of the reading assignment to return.

Returns

200 Assignment with its assigned meter stops

Show attributes
idstring · required
tenant_idstring · required
round_idstring · required
reader_idstring · required
meter_idsarray of string · required
statusstring · required

one of assigned, in_progress, completed, cancelled

assigned_bystring · required
assigned_atstring (date-time) · required
due_atstring · optional · nullable
started_atstring · optional · nullable
completed_atstring · optional · nullable
cancelled_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions business:reading-assignments:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/reading-assignments/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "rea_2EipDoOH7eqBZSWv5EopbOSVrAi",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "round_id": "rou_2yOn3qm15M8hnMSBVgwddaODZOG",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "status": "assigned",
  "assigned_by": "assigned by",
  "assigned_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z",
  "cancelled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Start, complete, or cancel an assignment

Logs

PATCH /reading-assignments/{id}/status

Moves a reading assignment to a new status and returns 204 with no body. Allowed moves are assigned to in_progress or cancelled, and in_progress to completed or cancelled; starting work requires the round to be open or in_progress, and completing requires the round to be in_progress. Any other move returns 409, an unknown status value returns 400, and sending the current status again is a no-op. Requires business:reading-assignments:manage.

Parameters

idstring · path · required

ID of the reading assignment whose status to change.

Body application/json

statusstring · required

one of assigned, in_progress, completed, cancelled

Returns

204 Assignment status changed

Permissions business:reading-assignments:manage · Roles: admin, field_supervisor, operations, owner

curl -X PATCH "$BUSINESS_API/reading-assignments/{id}/status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "assigned"
}'
Response 204

Assignment status changed