Field visits

Base URL: $BUSINESS_API

The object

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

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.

assignment_idstring · optional
route_idstring · optional
cycle_idstring · optional
reader_idstring · required
visited_atstring (date-time) · required
outcomestring · required

one of read, inaccessible, damaged, not_found

reading_idstring · optional
latitudenumber · optional
longitudenumber · optional
evidence_idsarray of string · optional
notesstring · optional
revisit_requiredboolean · required
revisit_reasonstring · optional
revisit_scheduled_atstring (date-time) · optional
created_atstring (date-time) · required
The object
{
  "id": "fie_2CaHRWCx7GgdfmOznKWVHUOVNas",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "visited_at": "2026-11-19T09:30:00Z",
  "outcome": "read",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "notes": "Leitura confirmada no local.",
  "revisit_required": true,
  "revisit_reason": "revisit reason",
  "revisit_scheduled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

List field visit records and inspection outcomes

Logs

GET /field-visits

Returns field visit records of the tenant with outcome, reader, location, evidence and revisit details. Filters combine, the handler also accepts route_id and cycle_id, and results are cursor-paginated (default 20, maximum 100). An unknown outcome value returns 400. Requires the business:field-visits:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

meter_idstring · query · optional

Return only visits to this meter.

account_idstring · query · optional

Return only visits to meters of this service account.

reader_idstring · query · optional

Return only visits recorded by this staff member (the identity that submitted the visit).

outcomestring · query · optional

Return only visits with this outcome: read, inaccessible, damaged or not_found; any other value returns 400.

one of read, inaccessible, damaged, not_found

revisit_requiredboolean · query · optional

When true or 1, return only visits that need a revisit; any other value returns only visits that do not; omit to include both.

Returns

200 Field visits list

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

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.

assignment_idstring · optional
route_idstring · optional
cycle_idstring · optional
reader_idstring · required
visited_atstring (date-time) · required
outcomestring · required

one of read, inaccessible, damaged, not_found

reading_idstring · optional
latitudenumber · optional
longitudenumber · optional
evidence_idsarray of string · optional
notesstring · optional
revisit_requiredboolean · required
revisit_reasonstring · optional
revisit_scheduled_atstring (date-time) · optional
created_atstring (date-time) · required
has_moreboolean · optional
next_cursorstring · optional

Errors 403

Permissions business:field-visits:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/field-visits" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "fie_2CaHRWCx7GgdfmOznKWVHUOVNas",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
      "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
      "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
      "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
      "visited_at": "2026-11-19T09:30:00Z",
      "outcome": "read",
      "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
      "latitude": -25.9653,
      "longitude": 32.5892,
      "evidence_ids": [
        "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
      ],
      "notes": "Leitura confirmada no local.",
      "revisit_required": true,
      "revisit_reason": "revisit reason",
      "revisit_scheduled_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Record field visit evidence, outcome, or revisit requirement

Logs

POST /field-visits

Records a visit by the calling staff member to an active meter and returns it with 201; the account is taken from the meter. With assignment_id, the assignment must belong to the caller, be in progress, include the meter and sit in an in-progress reading round, and the visit then carries its route and cycle. visited_at defaults to now and must lie between the meter's installation and five minutes in the future, and revisit_scheduled_at may not be in the past (400). An inactive meter or a round that is not in progress returns 409; an unknown meter or assignment returns 404.

Body application/json

meter_idstring · required
assignment_idstring · optional
visited_atstring (date-time) · optional
outcomestring · required

one of read, inaccessible, damaged, not_found

reading_idstring · optional
latitudenumber · optional
longitudenumber · optional
evidence_idsarray of string · optional
notesstring · optional
revisit_requiredboolean · optional
revisit_reasonstring · optional
revisit_scheduled_atstring (date-time) · optional

Returns

201 Field visit recorded

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

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.

assignment_idstring · optional
route_idstring · optional
cycle_idstring · optional
reader_idstring · required
visited_atstring (date-time) · required
outcomestring · required

one of read, inaccessible, damaged, not_found

reading_idstring · optional
latitudenumber · optional
longitudenumber · optional
evidence_idsarray of string · optional
notesstring · optional
revisit_requiredboolean · required
revisit_reasonstring · optional
revisit_scheduled_atstring (date-time) · optional
created_atstring (date-time) · required

Errors 400 · 403 · 404

Permissions business:field-visits:create · Roles: admin, field_reader, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/field-visits" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "visited_at": "2026-11-19T09:30:00Z",
  "outcome": "read",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "notes": "Leitura confirmada no local.",
  "revisit_required": true,
  "revisit_reason": "revisit reason",
  "revisit_scheduled_at": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "id": "fie_2CaHRWCx7GgdfmOznKWVHUOVNas",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "visited_at": "2026-11-19T09:30:00Z",
  "outcome": "read",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "notes": "Leitura confirmada no local.",
  "revisit_required": true,
  "revisit_reason": "revisit reason",
  "revisit_scheduled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

Get details of a recorded field visit

Logs

GET /field-visits/{id}

Returns one field visit with its outcome, reader, linked reading, coordinates, evidence IDs, notes and revisit details. Returns 404 when the visit is not in the tenant. Requires the business:field-visits:read permission.

Parameters

idstring · path · required

Identifier of the field visit (an fvs_ prefixed ID) within the current tenant.

Returns

200 Field visit details

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

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.

assignment_idstring · optional
route_idstring · optional
cycle_idstring · optional
reader_idstring · required
visited_atstring (date-time) · required
outcomestring · required

one of read, inaccessible, damaged, not_found

reading_idstring · optional
latitudenumber · optional
longitudenumber · optional
evidence_idsarray of string · optional
notesstring · optional
revisit_requiredboolean · required
revisit_reasonstring · optional
revisit_scheduled_atstring (date-time) · optional
created_atstring (date-time) · required

Errors 403 · 404

Permissions business:field-visits:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/field-visits/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "fie_2CaHRWCx7GgdfmOznKWVHUOVNas",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "reader_id": "rea_2z56md1eSXHYIhXoEFxw6B7cIbr",
  "visited_at": "2026-11-19T09:30:00Z",
  "outcome": "read",
  "reading_id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "latitude": -25.9653,
  "longitude": 32.5892,
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "notes": "Leitura confirmada no local.",
  "revisit_required": true,
  "revisit_reason": "revisit reason",
  "revisit_scheduled_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}