Metering API & integration reference

This guide covers three ways to read meter data from the Waltero platform.

Part 1 — Daily consumption from the Metering application. One call, one response, all meters in your organization, consumption already converted to the meter’s display units. Start here unless you specifically need raw values or a custom aggregation.

Part 2 — Raw meter readings from platform-api. The lower-level walkthrough: find devices → fetch their meter type → read meter.value.processed → apply the multiplier yourself. Use this when you need raw readings, an aggregation interval Part 1 doesn’t offer, or fields beyond consumption (battery, RSSI, temperature, …).

Part 3 — Meter value changelog (data-audit API). Track every correction to a sensor’s stored readings. Use this to answer “what data has changed since my last call?” — useful for replicating Waltero readings into your own system without missing post-hoc corrections.

A full OpenAPI 3 specification is available on request — contact your Waltero integration lead. For complete walkthroughs, error tables, and field references, download the companion PDF above.

Conventions

Is the base URL fixed? Yes — for your EMEA prod tenant, the host above is stable and won’t change as new customers onboard. Other regions and environments (APAC prod, EMEA staging, on-prem deployments) have different hosts but identical endpoint paths and request/response contracts.

BASE='https://qs0iya7cfk.execute-api.eu-central-1.amazonaws.com/prod'

TOKEN=$(curl -s -X POST "$BASE/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"you@example.com","password":"…"}' | jq -r .token)

Part 1 — Daily consumption (Metering application)

Fetch daily consumption per meter for every meter in your organization. One call per organization. The response contains one row per meter per day, with consumption already in the meter’s display units — no client-side multiplication, no delta math, no rollover handling.

Pin the version

The metering application is versioned. As long as you pin /v3/ in your URL, the response shape is frozen. The unversioned URL follows whatever Waltero has flagged as the current default — that pointer can move at any time. Pin /v3/ in any URL your integration depends on.

Find your organization UUID

GET /api/auth/me returns your user record plus accessible_organizations:

curl -s "$BASE/api/auth/me" \
  -H "Authorization: Bearer $TOKEN" | jq '{
    primary_org:    .user.organizations[0].organization_id,
    all_accessible: .accessible_organizations
  }'

Fetch daily consumption

ORG='00000000-0000-0000-0000-000000000001'
START='2026-05-18T22:00:00.000Z'
END='2026-05-25T22:00:00.000Z'

curl -s "$BASE/api/organizations/$ORG/applications/metering/v3/data/device-daily-consumption\
?startDate=$START\
&endDate=$END\
&resolution=day" \
  -H "Authorization: Bearer $TOKEN" | jq

The response is one row per (deviceId, date):

A meter with no readings for a day still appears, but with consumption: null and the date field omitted. Filter these before computing totals.

Parameters

Part 2 — Raw readings (platform-api)

When you need the raw meter value, a different aggregation interval, or device fields beyond consumption (battery, RSSI, temperature), call the platform API directly.

Find devices

curl -s "$BASE/api/organizations/$ORG/devices?limit=100" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {id, name, meter_type}'

Fetch raw telemetry

DEVICE='11111111-1111-1111-1111-111111111101'

curl -s "$BASE/api/devices/$DEVICE/telemetry\
?startDate=$START\
&endDate=$END\
&fields=meter.value.processed,meter.value.raw,battery.voltage,connection.rssi" \
  -H "Authorization: Bearer $TOKEN" | jq

The meter.value.processed field is what the dashboard displays. The meter.value.raw field is the unconverted reading — multiply by the meter’s multiplier (returned by GET /api/devices/{id}) for the display value.

Available fields per device

Different sensor variants expose different fields. Discover what’s available:

curl -s "$BASE/api/devices/$DEVICE/fields" \
  -H "Authorization: Bearer $TOKEN" | jq

Returns a grouped list — meter, battery, connection, meta — with the exact field names that variant supports.

Part 3 — The data-audit changelog

Sensors sometimes have their stored readings corrected post-hoc — usually when a misaligned digit is re-recognized after a manual review. The data-audit endpoint surfaces every change to a sensor’s history so you can keep a mirror in sync without missing late corrections.

curl -s "$BASE/api/organizations/$ORG/data-audit/changes\
?since=2026-05-25T00:00:00.000Z\
&limit=200" \
  -H "Authorization: Bearer $TOKEN" | jq

Each change row identifies the device, the affected timestamp, the previous value, the new value, and the actor (system / user). Poll this endpoint on a schedule that matches your tolerance for stale data — most integrations poll once an hour.

Errors you might hit

Where to go next

Download the PDF version of this guide for the complete walkthrough including field references, error handling patterns, and worked examples.

For onboarding new sensors before integrating, see the W-Sensor installation quick start. For mechanical fitting and mount selection, see the Mounts guide (coming soon).