# 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:read` and `business:readings:read` to look things up, `business:readings:create` to send readings, and `business:readings:review` to accept or reject them.

## 1. Pick an active meter

Readings are taken only for meters whose status is `active`.

```bash
curl -sS "$BUSINESS_API/meters?status=active&limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data[0].id` starts with `mtr_`. Note its `unit` (`m3` for the water meters in this example) and `precision`, the number of decimal places a value may carry.

## 2. Look up the last accepted reading

Your next value should be equal to or above this one, unless the dial has rolled over.

```bash
curl -sS "$BUSINESS_API/readings?meter_id=mtr_3aIlrbKkunoeedv9MrqJIL2rdzh&status=accepted&limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data[0].value` is a decimal string such as `"1231.870"`, and `data[0].measured_at` tells you when it was read.

## 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.

```bash
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:

```json
{
  "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"
}
```

✓ Checkpoint: `status` is `submitted`. When the check distrusts the value you get `review_required` instead, with `review_reason_code` saying why: `reading_review.earlier_or_lower` for a value below the previous one, or `reading_review.above_three_month_average` for usage above three times the average of the last three months.

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

```bash
curl -sS -X POST "$BUSINESS_API/readings/rdg_3ocbvsab7pwoXJTg5ThlDX47TVc/accept" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: the reading comes back with `"status": "accepted"` and with `reviewed_by` and `reviewed_at` set. To turn it down, call `POST /readings/{id}/reject` with `{"reason":"Photo is unreadable"}` (1 to 500 characters). Both calls work only on `submitted` or `review_required` readings and answer `409` for any other status. An accepted reading is fixed with `POST /readings/{id}/corrections`, which creates a new reading and marks the original `superseded`.

## 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.

## Next steps

- [Issue invoices from accepted readings](/docs/guides/issue-invoices)
- [Listen for reading.accepted and reading.flagged](/docs/guides/listen-webhooks)
- [Idempotency: the Idempotency-Key header on other POSTs](/docs/getting-started/idempotency)
- [Errors: reading error_code and invalid_params](/docs/getting-started/errors)

