Meters: Meters

Base URL: $BUSINESS_API

List tenant-owned meters

Logs

GET /meters

Returns the tenant's meters with cursor pagination. The optional q parameter searches meters and also matches meters of accounts whose holder matches the text. An unknown status value returns 400. Requires the business:meters:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

qstring · query · optional

Resource-specific text search.

account_idstring · query · optional

Returns only meters assigned to this customer account.

statusstring · query · optional

Operational status: active, inactive or retired; any other value returns 400.

one of active, inactive, retired

device_statusstring · query · optional

Physical device state: in_warehouse, installed, in_testing or scrapped.

one of in_warehouse, installed, in_testing, scrapped

Returns

200 Meters in the authenticated utility tenant

Show attributes
dataarray of Meter · required
Show child attributes
meter_rolestring · optional

one of standard, master, submeter

parent_meter_idstring · optional
master_billing_modestring · optional

one of gross, net_of_submeters, monitor_only

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

serial_numberstring · required
unitstring · required
precisioninteger · required
manufacturerstring · optional
modelstring · optional
meter_typestring · optional

one of mechanical, ultrasonic, electromagnetic, smart, prepaid

diameter_mminteger · optional
unit_of_measurestring · optional
dial_digitsinteger · optional
dial_decimalsinteger · optional
pulse_multiplierstring · optional
maximum_readingstring · optional
device_statusstring · required

one of in_warehouse, installed, in_testing, scrapped

rollover_valuestring · optional

Optional meter modulus used to calculate a reviewed rollover consumption.

statusstring · required

one of active, inactive, retired

last_reset_atstring · optional · nullable
last_reset_valuestring · optional
installed_atstring (date-time) · required
removed_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 403

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

curl -X GET "$BUSINESS_API/meters" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "meter_role": "standard",
      "parent_meter_id": "par_2QITx82Lf0WbZUKXhKu7TOgdRag",
      "master_billing_mode": "gross",
      "id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "serial_number": "SER-2026-000142",
      "unit": "unit",
      "precision": 0,
      "manufacturer": "manufacturer",
      "model": "model",
      "meter_type": "mechanical",
      "diameter_mm": 1,
      "unit_of_measure": "unit of measure",
      "dial_digits": 1,
      "dial_decimals": 1,
      "pulse_multiplier": "pulse multiplier",
      "maximum_reading": "maximum reading",
      "device_status": "in_warehouse",
      "rollover_value": "rollover value",
      "status": "active",
      "last_reset_at": "2026-11-19T09:30:00Z",
      "last_reset_value": "last reset value",
      "installed_at": "2026-11-19T09:30:00Z",
      "removed_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"
}

Register a meter against a utility account

Logs

POST /meters

Registers a meter with its serial number (stored upper case), unit, precision (0 to 9) and optional device details, and returns it with 201. A meter registered as in_warehouse or in_testing may have no account and starts inactive; otherwise account_id must name an active account and the meter starts active and installed. Returns 400 for invalid fields or an installed_at in the future, and 404 when the account does not exist. Requires the business:meters:create permission.

Body application/json

manufacturerstring · optional
modelstring · optional
meter_typestring · optional
diameter_mminteger · optional
dial_digitsinteger · optional

Integer dial digits; derives maximum_reading (99999 for five digits).

dial_decimalsinteger · optional
pulse_multiplierstring · optional
maximum_readingstring · optional

Largest dial value; rollover modulus is this plus one smallest dial unit.

device_statusstring · optional

A warehouse or testing meter needs no account.

one of in_warehouse, in_testing, installed

account_idstring · required
serial_numberstring · required
unitstring · required
precisioninteger · required
rollover_valuestring · optional
installed_atstring (date-time) · optional

Returns

201 Meter registered

Show attributes
meter_rolestring · optional

one of standard, master, submeter

parent_meter_idstring · optional
master_billing_modestring · optional

one of gross, net_of_submeters, monitor_only

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

serial_numberstring · required
unitstring · required
precisioninteger · required
manufacturerstring · optional
modelstring · optional
meter_typestring · optional

one of mechanical, ultrasonic, electromagnetic, smart, prepaid

diameter_mminteger · optional
unit_of_measurestring · optional
dial_digitsinteger · optional
dial_decimalsinteger · optional
pulse_multiplierstring · optional
maximum_readingstring · optional
device_statusstring · required

one of in_warehouse, installed, in_testing, scrapped

rollover_valuestring · optional

Optional meter modulus used to calculate a reviewed rollover consumption.

statusstring · required

one of active, inactive, retired

last_reset_atstring · optional · nullable
last_reset_valuestring · optional
installed_atstring (date-time) · required
removed_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 409

Permissions business:meters:create · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/meters" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "manufacturer": "manufacturer",
  "model": "model",
  "meter_type": "meter type",
  "diameter_mm": 1,
  "dial_digits": 1,
  "dial_decimals": 0,
  "pulse_multiplier": "pulse multiplier",
  "maximum_reading": "maximum reading",
  "device_status": "in_warehouse",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "serial_number": "SER-2026-000142",
  "unit": "unit",
  "precision": 0,
  "rollover_value": "rollover value",
  "installed_at": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "meter_role": "standard",
  "parent_meter_id": "par_2QITx82Lf0WbZUKXhKu7TOgdRag",
  "master_billing_mode": "gross",
  "id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "serial_number": "SER-2026-000142",
  "unit": "unit",
  "precision": 0,
  "manufacturer": "manufacturer",
  "model": "model",
  "meter_type": "mechanical",
  "diameter_mm": 1,
  "unit_of_measure": "unit of measure",
  "dial_digits": 1,
  "dial_decimals": 1,
  "pulse_multiplier": "pulse multiplier",
  "maximum_reading": "maximum reading",
  "device_status": "in_warehouse",
  "rollover_value": "rollover value",
  "status": "active",
  "last_reset_at": "2026-11-19T09:30:00Z",
  "last_reset_value": "last reset value",
  "installed_at": "2026-11-19T09:30:00Z",
  "removed_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Install meter

Logs

POST /meters/install

Install a meter on a connection, writing the installation, start reading and bi-temporal binding atomically

Installs a meter on a connection in one transaction: it records the installation, binds the meter to the connection from installed_at, marks the meter active and installed, records an accepted initial reading, and emits a meter.installed event. idempotency_key is required; repeating it with the same meter and connection returns the existing installation, and with different values returns 409. Returns 409 when the connection or the meter already has an open installation or the meter is scrapped, and 400 when no active account can be resolved. Requires the business:meters:manage permission.

Body application/json

connection_idstring · required
meter_idstring · required
account_idstring · optional
installed_atstring (date-time) · optional
initial_readingstring · required
security_seal_numberstring · optional
idempotency_keystring · required
location_idstring · optional

Store or van the meter is taken from; inventory refuses the installation when its serial is elsewhere.

Returns

201 Installation recorded

Show attributes
idstring · required
tenant_idstring · required
connection_idstring · required
connection_holder_namestring · optional

Display name of the customer who holds the referenced connection. 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.

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.

installed_atstring (date-time) · required
initial_readingstring · required
removed_atstring · optional · nullable
final_readingstring · optional
exchange_reasonstring · optional
installed_bystring · required
security_seal_numberstring · optional
replaced_installation_idstring · optional
idempotency_keystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404 · 409

Permissions business:meters:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/meters/install" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "installed_at": "2026-11-19T09:30:00Z",
  "initial_reading": "initial reading",
  "security_seal_number": "SEC-2026-000142",
  "idempotency_key": "idempotency key",
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx"
}'
Response 201
{
  "id": "met_2yk9v6SNluyXngonlgs1hccPdGU",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "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",
  "installed_at": "2026-11-19T09:30:00Z",
  "initial_reading": "initial reading",
  "removed_at": "2026-11-19T09:30:00Z",
  "final_reading": "final reading",
  "exchange_reason": "exchange reason",
  "installed_by": "installed by",
  "security_seal_number": "SEC-2026-000142",
  "replaced_installation_id": "rep_2rLgATXYm9pMiLbYyNLwCPHAGTv",
  "idempotency_key": "idempotency key",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Replace an installed meter atomically

Logs

POST /meters/exchange

Closes the old installation, opens the new one, records final and start readings, flips both devices and supersedes the bi-temporal binding in one transaction. Idempotent on idempotency_key.

Body application/json

connection_idstring · required
old_meter_idstring · required
new_meter_idstring · required
exchanged_atstring (date-time) · optional
final_readingstring · required
start_readingstring · required
exchange_reasonstring · required
security_seal_numberstring · optional
old_meter_statusstring · optional

one of in_testing, in_warehouse, scrapped

idempotency_keystring · required
new_meter_location_idstring · optional

Store or van the new meter is taken from.

return_location_idstring · optional

Where an old meter returned in_warehouse goes; the default warehouse when empty.

Returns

201 Exchange recorded

Show attributes
closed_installationobject · optional
Show child attributes
idstring · required
tenant_idstring · required
connection_idstring · required
connection_holder_namestring · optional

Display name of the customer who holds the referenced connection. 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.

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.

installed_atstring (date-time) · required
initial_readingstring · required
removed_atstring · optional · nullable
final_readingstring · optional
exchange_reasonstring · optional
installed_bystring · required
security_seal_numberstring · optional
replaced_installation_idstring · optional
idempotency_keystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
new_installationobject · optional
Show child attributes
idstring · required
tenant_idstring · required
connection_idstring · required
connection_holder_namestring · optional

Display name of the customer who holds the referenced connection. 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.

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.

installed_atstring (date-time) · required
initial_readingstring · required
removed_atstring · optional · nullable
final_readingstring · optional
exchange_reasonstring · optional
installed_bystring · required
security_seal_numberstring · optional
replaced_installation_idstring · optional
idempotency_keystring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
final_readingobject · optional
Show child 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
start_readingobject · optional
Show child 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
old_meterobject · optional
Show child attributes
meter_rolestring · optional

one of standard, master, submeter

parent_meter_idstring · optional
master_billing_modestring · optional

one of gross, net_of_submeters, monitor_only

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

serial_numberstring · required
unitstring · required
precisioninteger · required
manufacturerstring · optional
modelstring · optional
meter_typestring · optional

one of mechanical, ultrasonic, electromagnetic, smart, prepaid

diameter_mminteger · optional
unit_of_measurestring · optional
dial_digitsinteger · optional
dial_decimalsinteger · optional
pulse_multiplierstring · optional
maximum_readingstring · optional
device_statusstring · required

one of in_warehouse, installed, in_testing, scrapped

rollover_valuestring · optional

Optional meter modulus used to calculate a reviewed rollover consumption.

statusstring · required

one of active, inactive, retired

last_reset_atstring · optional · nullable
last_reset_valuestring · optional
installed_atstring (date-time) · required
removed_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required
new_meterobject · optional
Show child attributes
meter_rolestring · optional

one of standard, master, submeter

parent_meter_idstring · optional
master_billing_modestring · optional

one of gross, net_of_submeters, monitor_only

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

serial_numberstring · required
unitstring · required
precisioninteger · required
manufacturerstring · optional
modelstring · optional
meter_typestring · optional

one of mechanical, ultrasonic, electromagnetic, smart, prepaid

diameter_mminteger · optional
unit_of_measurestring · optional
dial_digitsinteger · optional
dial_decimalsinteger · optional
pulse_multiplierstring · optional
maximum_readingstring · optional
device_statusstring · required

one of in_warehouse, installed, in_testing, scrapped

rollover_valuestring · optional

Optional meter modulus used to calculate a reviewed rollover consumption.

statusstring · required

one of active, inactive, retired

last_reset_atstring · optional · nullable
last_reset_valuestring · optional
installed_atstring (date-time) · required
removed_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404 · 409

Permissions business:meters:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/meters/exchange" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "old_meter_id": "old_2hHUIZvWSjJSipd8YNlqmL7U0J3",
  "new_meter_id": "new_2SyBNEGFJ0e39OoPzWORT4S7Pmg",
  "exchanged_at": "2026-11-19T09:30:00Z",
  "final_reading": "final reading",
  "start_reading": "start reading",
  "exchange_reason": "exchange reason",
  "security_seal_number": "SEC-2026-000142",
  "old_meter_status": "in_testing",
  "idempotency_key": "idempotency key",
  "new_meter_location_id": "new_2Mu5dUydZUuVVEq71I4zrwoXnYG",
  "return_location_id": "ret_2YePJOWzHcgzbQInHUG75oEzL0i"
}'
Response 201
{
  "closed_installation": {
    "id": "met_2yk9v6SNluyXngonlgs1hccPdGU",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
    "connection_holder_name": "Ana Matsinhe",
    "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",
    "installed_at": "2026-11-19T09:30:00Z",
    "initial_reading": "initial reading",
    "removed_at": "2026-11-19T09:30:00Z",
    "final_reading": "final reading",
    "exchange_reason": "exchange reason",
    "installed_by": "installed by",
    "security_seal_number": "SEC-2026-000142",
    "replaced_installation_id": "rep_2rLgATXYm9pMiLbYyNLwCPHAGTv",
    "idempotency_key": "idempotency key",
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "new_installation": {
    "id": "met_2yk9v6SNluyXngonlgs1hccPdGU",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
    "connection_holder_name": "Ana Matsinhe",
    "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",
    "installed_at": "2026-11-19T09:30:00Z",
    "initial_reading": "initial reading",
    "removed_at": "2026-11-19T09:30:00Z",
    "final_reading": "final reading",
    "exchange_reason": "exchange reason",
    "installed_by": "installed by",
    "security_seal_number": "SEC-2026-000142",
    "replaced_installation_id": "rep_2rLgATXYm9pMiLbYyNLwCPHAGTv",
    "idempotency_key": "idempotency key",
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "final_reading": {
    "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"
  },
  "start_reading": {
    "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"
  },
  "old_meter": {
    "meter_role": "standard",
    "parent_meter_id": "par_2QITx82Lf0WbZUKXhKu7TOgdRag",
    "master_billing_mode": "gross",
    "id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
    "account_number": "ACC-2026-000142",
    "account_holder_name": "Ana Matsinhe",
    "serial_number": "SER-2026-000142",
    "unit": "unit",
    "precision": 0,
    "manufacturer": "manufacturer",
    "model": "model",
    "meter_type": "mechanical",
    "diameter_mm": 1,
    "unit_of_measure": "unit of measure",
    "dial_digits": 1,
    "dial_decimals": 1,
    "pulse_multiplier": "pulse multiplier",
    "maximum_reading": "maximum reading",
    "device_status": "in_warehouse",
    "rollover_value": "rollover value",
    "status": "active",
    "last_reset_at": "2026-11-19T09:30:00Z",
    "last_reset_value": "last reset value",
    "installed_at": "2026-11-19T09:30:00Z",
    "removed_at": "2026-11-19T09:30:00Z",
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "new_meter": {
    "meter_role": "standard",
    "parent_meter_id": "par_2QITx82Lf0WbZUKXhKu7TOgdRag",
    "master_billing_mode": "gross",
    "id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
    "account_number": "ACC-2026-000142",
    "account_holder_name": "Ana Matsinhe",
    "serial_number": "SER-2026-000142",
    "unit": "unit",
    "precision": 0,
    "manufacturer": "manufacturer",
    "model": "model",
    "meter_type": "mechanical",
    "diameter_mm": 1,
    "unit_of_measure": "unit of measure",
    "dial_digits": 1,
    "dial_decimals": 1,
    "pulse_multiplier": "pulse multiplier",
    "maximum_reading": "maximum reading",
    "device_status": "in_warehouse",
    "rollover_value": "rollover value",
    "status": "active",
    "last_reset_at": "2026-11-19T09:30:00Z",
    "last_reset_value": "last reset value",
    "installed_at": "2026-11-19T09:30:00Z",
    "removed_at": "2026-11-19T09:30:00Z",
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  }
}

Get a tenant-owned meter

Logs

GET /meters/{id}

Returns the meter with its serial number, account, unit and precision, status, device status, role (standard, master or submeter) and installation dates. Returns 404 when the meter does not exist in the caller's tenant. Requires the business:meters:read permission.

Parameters

idstring · path · required

ID of the meter in the caller's tenant.

Returns

200 Meter details

Show attributes
meter_rolestring · optional

one of standard, master, submeter

parent_meter_idstring · optional
master_billing_modestring · optional

one of gross, net_of_submeters, monitor_only

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

serial_numberstring · required
unitstring · required
precisioninteger · required
manufacturerstring · optional
modelstring · optional
meter_typestring · optional

one of mechanical, ultrasonic, electromagnetic, smart, prepaid

diameter_mminteger · optional
unit_of_measurestring · optional
dial_digitsinteger · optional
dial_decimalsinteger · optional
pulse_multiplierstring · optional
maximum_readingstring · optional
device_statusstring · required

one of in_warehouse, installed, in_testing, scrapped

rollover_valuestring · optional

Optional meter modulus used to calculate a reviewed rollover consumption.

statusstring · required

one of active, inactive, retired

last_reset_atstring · optional · nullable
last_reset_valuestring · optional
installed_atstring (date-time) · required
removed_atstring · optional · nullable
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 403 · 404

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

curl -X GET "$BUSINESS_API/meters/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "meter_role": "standard",
  "parent_meter_id": "par_2QITx82Lf0WbZUKXhKu7TOgdRag",
  "master_billing_mode": "gross",
  "id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "serial_number": "SER-2026-000142",
  "unit": "unit",
  "precision": 0,
  "manufacturer": "manufacturer",
  "model": "model",
  "meter_type": "mechanical",
  "diameter_mm": 1,
  "unit_of_measure": "unit of measure",
  "dial_digits": 1,
  "dial_decimals": 1,
  "pulse_multiplier": "pulse multiplier",
  "maximum_reading": "maximum reading",
  "device_status": "in_warehouse",
  "rollover_value": "rollover value",
  "status": "active",
  "last_reset_at": "2026-11-19T09:30:00Z",
  "last_reset_value": "last reset value",
  "installed_at": "2026-11-19T09:30:00Z",
  "removed_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}