Readings

Base URL: $BUSINESS_API

The object

meter_serialstring · optional

The meter's serial number; present on consumer reading listings

connection_idstring · optional
connection_holder_namestring · optional

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

previous_valuestring · optional
raw_consumptionstring · optional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · optional
has_rolloverboolean · optional
sourcestring · optional

one of mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · optional

one of passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · optional
is_billedboolean · optional
idstring · required
tenant_idstring · required
meter_idstring · required
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.

route_idstring · optional
cycle_idstring · optional
assignment_idstring · optional
valuestring · required
unitstring · required
measured_atstring (date-time) · required
received_atstring (date-time) · required
methodstring · required

one of manual, consumer, remote, imported, estimated

submitted_bystring · required
source_idstring · optional
external_idstring · optional
client_reading_idstring · required
idempotency_keystring · required
statusstring · required

one of submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · optional
estimate_reasonstring · optional
review_reasonstring · optional
review_reason_codestring · optional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · optional
reviewed_bystring · optional
reviewed_atstring · optional · nullable
supersedes_idstring · optional
superseded_by_idstring · optional
correction_reasonstring · optional
created_atstring (date-time) · required
The object
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

List plausibility review

Logs

GET /readings/plausibility-review

Readings awaiting plausibility review with three-month context

Returns the review queue: readings in review_required status that the plausibility check flagged as high, negative or zero consumption, a page at a time (limit default 20, maximum 100, and after). Each item adds up to 12 accepted readings of the same meter from the previous three months, their average consumption and the high-consumption threshold derived from it. Requires business:readings:read.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Flagged readings with average, threshold and recent accepted readings

Permissions business:readings:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/readings/plausibility-review" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Flagged readings with average, threshold and recent accepted readings

List utility readings with filters

Logs

GET /readings

Returns a cursor-paginated page of meter readings in the tenant, with value, unit, method, status, plausibility result and the route, cycle and assignment they came from. Filters combine, and limit (default 20, maximum 100) and after page the results. Requires business:readings:read.

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

Returns only readings taken on this meter ID.

account_idstring · query · optional

Returns only readings recorded for this account ID.

route_idstring · query · optional

Returns only readings taken while working this reading route ID.

cycle_idstring · query · optional

Returns only readings that belong to this reading cycle ID.

statusstring · query · optional

Returns only readings in this status: submitted, validating, accepted, review_required, rejected or superseded; any other value returns 400.

one of submitted, validating, accepted, review_required, rejected, superseded

methodstring · query · optional

Returns only readings captured this way: manual, consumer, remote, imported or estimated; any other value returns 400.

one of manual, consumer, remote, imported, estimated

measured_fromstring (date-time) · query · optional

RFC 3339 timestamp; returns only readings measured at or after this instant, and it must not be later than measured_to (400 otherwise).

measured_tostring (date-time) · query · optional

RFC 3339 timestamp; returns only readings measured at or before this instant.

Returns

200 Readings in the authenticated utility tenant

Permissions business:readings:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

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

Readings in the authenticated utility tenant

Submit a manual field reading for review

Logs

POST /readings

Records a reading taken by staff and returns 202 with the reading, whose status is submitted or review_required depending on the plausibility check; a manual reading also logs a field visit. meter_id, client_reading_id, idempotency_key, measured_at, value and the meter's unit are required, the meter must be active, and measured_at cannot be before installation or more than 5 minutes in the future. Retrying with the same idempotency_key and identical data returns the original reading, while different data returns 409. Sending a readings array instead records up to 500 readings and returns 207 with a per-item result.

Body application/json

meter_idstring · required
assignment_idstring · optional

Optional in-progress assignment that authorizes this field reading and supplies route/cycle provenance.

valuestring · required
unitstring · required
measured_atstring (date-time) · required
client_reading_idstring · required
idempotency_keystring · required
evidence_idsarray of string · optional
estimate_reasonstring · optional

Returns

202 Reading recorded for validation or review

Show attributes
meter_serialstring · optional

The meter's serial number; present on consumer reading listings

connection_idstring · optional
connection_holder_namestring · optional

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

previous_valuestring · optional
raw_consumptionstring · optional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · optional
has_rolloverboolean · optional
sourcestring · optional

one of mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · optional

one of passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · optional
is_billedboolean · optional
idstring · required
tenant_idstring · required
meter_idstring · required
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.

route_idstring · optional
cycle_idstring · optional
assignment_idstring · optional
valuestring · required
unitstring · required
measured_atstring (date-time) · required
received_atstring (date-time) · required
methodstring · required

one of manual, consumer, remote, imported, estimated

submitted_bystring · required
source_idstring · optional
external_idstring · optional
client_reading_idstring · required
idempotency_keystring · required
statusstring · required

one of submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · optional
estimate_reasonstring · optional
review_reasonstring · optional
review_reason_codestring · optional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · optional
reviewed_bystring · optional
reviewed_atstring · optional · nullable
supersedes_idstring · optional
superseded_by_idstring · optional
correction_reasonstring · optional
created_atstring (date-time) · required

Permissions business:readings:create · Roles: admin, field_reader, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/readings" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason"
}'
Response 202
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Get a tenant-owned reading

Logs

GET /readings/{id}

Returns one meter reading with its value, unit, method, status, plausibility result, evidence and review details. A reading that does not exist in the tenant returns 404. Requires business:readings:read.

Parameters

idstring · path · required

ID of the meter reading to return.

Returns

200 Reading details

Show attributes
meter_serialstring · optional

The meter's serial number; present on consumer reading listings

connection_idstring · optional
connection_holder_namestring · optional

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

previous_valuestring · optional
raw_consumptionstring · optional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · optional
has_rolloverboolean · optional
sourcestring · optional

one of mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · optional

one of passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · optional
is_billedboolean · optional
idstring · required
tenant_idstring · required
meter_idstring · required
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.

route_idstring · optional
cycle_idstring · optional
assignment_idstring · optional
valuestring · required
unitstring · required
measured_atstring (date-time) · required
received_atstring (date-time) · required
methodstring · required

one of manual, consumer, remote, imported, estimated

submitted_bystring · required
source_idstring · optional
external_idstring · optional
client_reading_idstring · required
idempotency_keystring · required
statusstring · required

one of submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · optional
estimate_reasonstring · optional
review_reasonstring · optional
review_reason_codestring · optional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · optional
reviewed_bystring · optional
reviewed_atstring · optional · nullable
supersedes_idstring · optional
superseded_by_idstring · optional
correction_reasonstring · optional
created_atstring (date-time) · required

Permissions business:readings:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/readings/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Accept a submitted or review-required reading

Logs

POST /readings/{id}/accept

Accepts a reading so it can be used for consumption and billing, records the reviewer and the status change, and returns the updated reading. Only readings in submitted or review_required status can be accepted; any other status returns 409. Requires business:readings:review.

Parameters

idstring · path · required

ID of the meter reading to accept.

Returns

200 Accepted reading

Show attributes
meter_serialstring · optional

The meter's serial number; present on consumer reading listings

connection_idstring · optional
connection_holder_namestring · optional

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

previous_valuestring · optional
raw_consumptionstring · optional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · optional
has_rolloverboolean · optional
sourcestring · optional

one of mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · optional

one of passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · optional
is_billedboolean · optional
idstring · required
tenant_idstring · required
meter_idstring · required
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.

route_idstring · optional
cycle_idstring · optional
assignment_idstring · optional
valuestring · required
unitstring · required
measured_atstring (date-time) · required
received_atstring (date-time) · required
methodstring · required

one of manual, consumer, remote, imported, estimated

submitted_bystring · required
source_idstring · optional
external_idstring · optional
client_reading_idstring · required
idempotency_keystring · required
statusstring · required

one of submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · optional
estimate_reasonstring · optional
review_reasonstring · optional
review_reason_codestring · optional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · optional
reviewed_bystring · optional
reviewed_atstring · optional · nullable
supersedes_idstring · optional
superseded_by_idstring · optional
correction_reasonstring · optional
created_atstring (date-time) · required

Permissions business:readings:review · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/readings/{id}/accept" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Reject a submitted or review-required reading with a reason

Logs

POST /readings/{id}/reject

Rejects a reading so it is not used for consumption or billing, records the reviewer, the reason and the status change, and returns the updated reading. A reason of 1 to 500 characters is required (400 otherwise). Only readings in submitted or review_required status can be rejected; any other status returns 409. Requires business:readings:review.

Parameters

idstring · path · required

ID of the meter reading to reject.

Body application/json

reasonstring · required

Returns

200 Rejected reading

Show attributes
meter_serialstring · optional

The meter's serial number; present on consumer reading listings

connection_idstring · optional
connection_holder_namestring · optional

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

previous_valuestring · optional
raw_consumptionstring · optional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · optional
has_rolloverboolean · optional
sourcestring · optional

one of mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · optional

one of passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · optional
is_billedboolean · optional
idstring · required
tenant_idstring · required
meter_idstring · required
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.

route_idstring · optional
cycle_idstring · optional
assignment_idstring · optional
valuestring · required
unitstring · required
measured_atstring (date-time) · required
received_atstring (date-time) · required
methodstring · required

one of manual, consumer, remote, imported, estimated

submitted_bystring · required
source_idstring · optional
external_idstring · optional
client_reading_idstring · required
idempotency_keystring · required
statusstring · required

one of submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · optional
estimate_reasonstring · optional
review_reasonstring · optional
review_reason_codestring · optional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · optional
reviewed_bystring · optional
reviewed_atstring · optional · nullable
supersedes_idstring · optional
superseded_by_idstring · optional
correction_reasonstring · optional
created_atstring (date-time) · required

Permissions business:readings:review · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/readings/{id}/reject" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}

Correct accepted meter reading

Logs

POST /readings/{id}/corrections

Create an immutable correction that supersedes an accepted reading

The accepted source observation remains preserved as a superseded record; the correction requires a reason and idempotency key.

Parameters

idstring · path · required

ID of the accepted meter reading to correct; the correction is created as a new reading that supersedes it.

Body application/json

valuestring · required
reasonstring · required
idempotency_keystring · required

Returns

201 Corrected reading created

Show attributes
meter_serialstring · optional

The meter's serial number; present on consumer reading listings

connection_idstring · optional
connection_holder_namestring · optional

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

previous_valuestring · optional
raw_consumptionstring · optional

Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.

raw_consumption_microlitresinteger (int64) · optional
has_rolloverboolean · optional
sourcestring · optional

one of mobile_reader, customer_self_reading, ami_interval, office_estimate

plausibility_statusstring · optional

one of passed, flagged_high, flagged_negative, flagged_zero, verified_manual

photo_evidencestring · optional
is_billedboolean · optional
idstring · required
tenant_idstring · required
meter_idstring · required
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.

route_idstring · optional
cycle_idstring · optional
assignment_idstring · optional
valuestring · required
unitstring · required
measured_atstring (date-time) · required
received_atstring (date-time) · required
methodstring · required

one of manual, consumer, remote, imported, estimated

submitted_bystring · required
source_idstring · optional
external_idstring · optional
client_reading_idstring · required
idempotency_keystring · required
statusstring · required

one of submitted, validating, accepted, review_required, rejected, superseded

evidence_idsarray of string · optional
estimate_reasonstring · optional
review_reasonstring · optional
review_reason_codestring · optional

Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.

rejection_reasonstring · optional
reviewed_bystring · optional
reviewed_atstring · optional · nullable
supersedes_idstring · optional
superseded_by_idstring · optional
correction_reasonstring · optional
created_atstring (date-time) · required

Permissions business:readings:correct · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/readings/{id}/corrections" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "value": "value",
  "reason": "Leitura confirmada no local.",
  "idempotency_key": "idempotency key"
}'
Response 201
{
  "meter_serial": "meter serial",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "previous_value": "previous value",
  "raw_consumption": "raw consumption",
  "raw_consumption_microlitres": 1342,
  "has_rollover": true,
  "source": "mobile_reader",
  "plausibility_status": "passed",
  "photo_evidence": "photo evidence",
  "is_billed": true,
  "id": "rdg_2o0xXwujnSgR9QIvVEWblWSv7u0",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "route_id": "rte_2Tzu6NZioJBSiX9CSX5qObtq4Zt",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "assignment_id": "ass_2bVAYnXSmDHuMvxsMpR2Q93SOVR",
  "value": "value",
  "unit": "unit",
  "measured_at": "2026-11-19T09:30:00Z",
  "received_at": "2026-11-19T09:30:00Z",
  "method": "manual",
  "submitted_by": "submitted by",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "external_id": "ext_29hSSzf2mTlOMhPS6LZmabb6s5h",
  "client_reading_id": "cli_20odFUijr6eh1g69pygb9smdNCU",
  "idempotency_key": "idempotency key",
  "status": "submitted",
  "evidence_ids": [
    "evi_2N98GhhgsvHGkNNqQ3LICnXai7r"
  ],
  "estimate_reason": "estimate reason",
  "review_reason": "review reason",
  "review_reason_code": "REV-2026-000142",
  "rejection_reason": "rejection reason",
  "reviewed_by": "reviewed by",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "supersedes_id": "sup_2ZzC0N30W7dG4lhc0j9MWD38E9H",
  "superseded_by_id": "sup_2CCzv2SV1C8FhKeH3QOr5AY7LOi",
  "correction_reason": "correction reason",
  "created_at": "2026-11-19T09:30:00Z"
}