Meter inspection requests

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
account_idstring · required
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.

meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

identity_idstring · required
requester_namestring · optional

Who filed it, which can differ from the account holder.

reasonstring · required
idempotency_keystring · optional
kindstring · optional

one of consumer, field_reread

reading_idstring · optional
statusstring · required

one of open, scheduled, completed, cancelled

scheduled_atstring · optional · nullable
resolutionstring · optional
resolved_bystring · optional
resolved_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "met_22OXlyuNjQGrXkQbdCkn18WvtcE",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
  "requester_name": "Ana Matsinhe",
  "reason": "Leitura confirmada no local.",
  "idempotency_key": "idempotency key",
  "kind": "consumer",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "status": "open",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "resolution": "resolution",
  "resolved_by": "resolved by",
  "resolved_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List consumer and field-reader meter-inspection requests

Logs

GET /meter-inspection-requests

Returns inspection requests for the tenant's meters, both those raised by consumers and the field re-reads raised by staff, with cursor pagination. Filters combine with AND; an unknown status returns 400. Requires the business:inspection-requests:read permission.

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

Returns only requests raised for this customer account.

meter_idstring · query · optional

Returns only requests for this meter.

statusstring · query · optional

Request state: open, scheduled, completed or cancelled; any other value returns 400.

one of open, scheduled, completed, cancelled

kindstring · query · optional

Who raised the request: consumer for a request from the account holder, or field_reread for a re-read raised by staff.

one of consumer, field_reread

Returns

200 Tenant-scoped inspection requests

Show attributes
dataarray of MeterInspectionRequest · required
Show child attributes
idstring · required
tenant_idstring · required
account_idstring · required
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.

meter_idstring · required
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

identity_idstring · required
requester_namestring · optional

Who filed it, which can differ from the account holder.

reasonstring · required
idempotency_keystring · optional
kindstring · optional

one of consumer, field_reread

reading_idstring · optional
statusstring · required

one of open, scheduled, completed, cancelled

scheduled_atstring · optional · nullable
resolutionstring · optional
resolved_bystring · optional
resolved_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 403

Permissions business:inspection-requests:read · Roles: admin, analyst, customer_service, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/meter-inspection-requests" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "met_22OXlyuNjQGrXkQbdCkn18WvtcE",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
      "requester_name": "Ana Matsinhe",
      "reason": "Leitura confirmada no local.",
      "idempotency_key": "idempotency key",
      "kind": "consumer",
      "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
      "status": "open",
      "scheduled_at": "2026-11-19T09:30:00Z",
      "resolution": "resolution",
      "resolved_by": "resolved by",
      "resolved_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Schedule, complete, or cancel an inspection request

Logs

PATCH /meter-inspection-requests/{id}/status

Moves an inspection request to a new status and returns 204 with no body. An open request can be scheduled (scheduled_at is required and must be in the future) or cancelled; only a scheduled request can be completed; completing or cancelling requires a non-empty resolution text. Returns 409 when the request's current status does not allow the change and 400 for a missing or invalid field. Requires the business:inspection-requests:manage permission.

Parameters

idstring · path · required

ID of the inspection request in the caller's tenant.

Body application/json

statusstring · required

one of scheduled, completed, cancelled

scheduled_atstring (date-time) · optional
resolutionstring · optional

Returns

204 Inspection request state updated

Errors 400 · 403 · 404 · 409

Permissions business:inspection-requests:manage · Roles: admin, field_supervisor, operations, owner

curl -X PATCH "$BUSINESS_API/meter-inspection-requests/{id}/status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "scheduled",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "resolution": "resolution"
}'
Response 204

Inspection request state updated