Record meter readings
Send readings through the API without duplicates on retry, read the plausibility check's verdict, and accept or reject each reading before it reaches billing.
What you will build#
An integration that takes values from another system (a field handheld, an exported sheet, a telemetry platform) and delivers them as meter readings. On arrival every reading goes through a plausibility check and lands as submitted or review_required; only once it is accepted does it count towards consumption and billing. By the end you will have sent a reading, repeated the request without creating a duplicate, and accepted the reading through the API.
Prerequisites#
- A sandbox with its sample data (installed meters with earlier readings).
- A test API key holding
business:meters:readandbusiness:readings:readto look things up,business:readings:createto send readings, andbusiness:readings:reviewto accept or reject them.
1. Pick an active meter#
Readings are taken only for meters whose status is active.
curl -sS "$BUSINESS_API/meters?status=active&limit=1" \
-H "Authorization: Bearer $API_KEY"
2. Look up the last accepted reading#
Your next value should be equal to or above this one, unless the dial has rolled over.
curl -sS "$BUSINESS_API/readings?meter_id=mtr_3aIlrbKkunoeedv9MrqJIL2rdzh&status=accepted&limit=1" \
-H "Authorization: Bearer $API_KEY"
3. Send the reading#
value is a string so no decimal places are lost. client_reading_id names the reading in your own system (up to 120 characters), and idempotency_key (up to 160) guards against repeated sends. measured_at cannot be earlier than the meter's installation or more than 5 minutes in the future, and unit must match the meter's unit.
curl -sS -X POST "$BUSINESS_API/readings" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"meter_id":"mtr_3aIlrbKkunoeedv9MrqJIL2rdzh","value":"1245.320","unit":"m3","measured_at":"2026-11-19T08:40:00Z","client_reading_id":"route-07-2026-11-0153","idempotency_key":"route-07-2026-11-0153"}'
202 Accepted response, abridged:
{
"id": "rdg_3ocbvsab7pwoXJTg5ThlDX47TVc",
"tenant_id": "ten_3HclVhrn01Vsbj8CEBWAUk6h4MV",
"meter_id": "mtr_3aIlrbKkunoeedv9MrqJIL2rdzh",
"account_id": "act_3eQrF3JmTj2ZXpkFlbdO36UPXGP",
"value": "1245.320",
"previous_value": "1231.870",
"raw_consumption": "13.450",
"unit": "m3",
"method": "manual",
"status": "submitted",
"plausibility_status": "passed",
"measured_at": "2026-11-19T08:40:00Z",
"received_at": "2026-11-19T08:41:07Z",
"client_reading_id": "route-07-2026-11-0153",
"idempotency_key": "route-07-2026-11-0153",
"submitted_by": "key_3f5kSeI9SXDLwgbb5hilkGVvprT",
"created_at": "2026-11-19T08:41:07Z"
}
Send the identical request again and you get the same reading back, with the same id. Reusing the idempotency_key with different data returns 409 with error_code request.idempotency_conflict. To send up to 500 readings in one call, post an object whose readings list holds one element per reading with the fields above; the 207 response carries results, giving the status and any error for each client_reading_id.
4. Accept or reject#
curl -sS -X POST "$BUSINESS_API/readings/rdg_3ocbvsab7pwoXJTg5ThlDX47TVc/accept" \
-H "Authorization: Bearer $API_KEY"
Test it#
In the dashboard the reading shows on the Readings page, and readings left in review_required also appear under Reading review, where a reviewer accepts or rejects them. Run gotactl webhooks listen --forward-to http://localhost:3000/hook --events reading.accepted,reading.flagged to watch reading.accepted arrive when you accept, and reading.flagged when the plausibility check marks a value. To look without curl, gotactl readings list --meter-id mtr_3aIlrbKkunoeedv9MrqJIL2rdzh lists the meter's readings.