Dmas

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
codestring · required
namestring · required
service_area_idstring · required
inflow_meter_idstring · optional
outflow_meter_idstring · optional
target_pressure_barnumber · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List District Metered Areas

Logs

GET /dmas

Returns the tenant's district metered areas (DMAs), newest first, with their code, name, service area, inflow and outflow meters and target pressure. Results are cursor-paginated (default 20, maximum 100); the handler also accepts service_area_id and a q search that matches name or code. Requires the network:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 DMAs

Show attributes
dataarray of DistrictMeteredArea · required
Show child attributes
idstring · required
tenant_idstring · required
codestring · required
namestring · required
service_area_idstring · required
inflow_meter_idstring · optional
outflow_meter_idstring · optional
target_pressure_barnumber · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional
total_countinteger · optional

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/dmas" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
      "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
      "target_pressure_bar": 1,
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

Register a DMA

Logs

POST /dmas

Creates a district metered area in the tenant and returns it with 201. code, name and service_area_id are required (400 when missing); inflow_meter_id, outflow_meter_id and target_pressure_bar are optional, and the inflow meter is what night-flow analysis reads. A duplicate DMA code returns 409. Requires the network:write permission.

Body application/json

codestring · required
namestring · required
service_area_idstring · required
inflow_meter_idstring · optional
outflow_meter_idstring · optional
target_pressure_barnumber · optional

Returns

201 DMA registered

Show attributes
idstring · required
tenant_idstring · required
codestring · required
namestring · required
service_area_idstring · required
inflow_meter_idstring · optional
outflow_meter_idstring · optional
target_pressure_barnumber · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions network:write · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/dmas" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1
}'
Response 201
{
  "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get District Metered Area details

Logs

GET /dmas/{id}

Returns one district metered area of the tenant, including its code, service area, inflow and outflow meter references and target pressure. Returns 404 when the DMA does not exist in the tenant. Requires the network:read permission.

Parameters

idstring · path · required

Identifier of the district metered area (a dma_ prefixed ID) within the current tenant.

Returns

200 District Metered Area details

Show attributes
idstring · required
tenant_idstring · required
codestring · required
namestring · required
service_area_idstring · required
inflow_meter_idstring · optional
outflow_meter_idstring · optional
target_pressure_barnumber · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/dmas/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Update dma

Logs

PUT /dmas/{id}

Update a DMA's name, service area, inflow and outflow meters or target pressure

Changes only the fields present in the body (name, service_area_id, inflow_meter_id, outflow_meter_id, target_pressure_bar) and returns the updated DMA; the code cannot be changed. name and service_area_id may not be set to an empty string (400), while the meter references can be cleared with an empty string. Returns 404 for an unknown DMA. Requires the network:write permission.

Parameters

idstring · path · required

Identifier of the district metered area to update within the current tenant.

Body application/json

namestring · optional
service_area_idstring · optional
inflow_meter_idstring · optional
outflow_meter_idstring · optional
target_pressure_barnumber · optional

Returns

200 Updated DMA

Show attributes
idstring · required
tenant_idstring · required
codestring · required
namestring · required
service_area_idstring · required
inflow_meter_idstring · optional
outflow_meter_idstring · optional
target_pressure_barnumber · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions network:write · Roles: admin, operations, owner

curl -X PUT "$BUSINESS_API/dmas/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1
}'
Response 200
{
  "id": "dis_23tmgLnkIX3uk5bAOhBQir5OGRd",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "inflow_meter_id": "inf_2bVsqJLmy71AotDagTtQg7dkEvN",
  "outflow_meter_id": "out_2OqdBqYxFeEJx8CvPccxRMK9JKu",
  "target_pressure_bar": 1,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

IWA water balance of one DMA

Logs

GET /dmas/{id}/water-balance

Computes an IWA-style water balance for one DMA over the window: system input volume, billed and unbilled authorised consumption, water losses and non-revenue water in litres, with non-revenue water as basis points of system input. Losses are split into apparent and real only when apparent_loss_bp is given, otherwise the split is reported as insufficient data; a status and warnings say when data is partial or missing. The window must be at most 366 days with to after from (400 otherwise); 404 for an unknown DMA. Requires the network:read permission.

Parameters

idstring · path · required

Identifier of the district metered area to balance.

fromstring · query · required

Required start of the balance period as an RFC 3339 timestamp.

tostring · query · required

Required end of the balance period as an RFC 3339 timestamp; it must be after from and no more than 366 days later.

apparent_loss_bpinteger · query · optional

Optional assumed apparent loss (meter under-registration and unauthorised use) as basis points of authorised consumption, an integer from 0 to 10000; when it exceeds total losses it is capped with a warning.

Returns

200 OK

Show attributes
scopestring · optional

one of system, dma

dma_idstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
statusstring · optional

one of computed, partial_data, insufficient_data

system_input_litersinteger · optional
billed_authorized_litersinteger · optional
unbilled_authorized_litersinteger · optional
authorized_consumption_litersinteger · optional
water_losses_litersinteger · optional
apparent_losses_litersinteger · optional · nullable
real_losses_litersinteger · optional · nullable
loss_splitstring · optional

one of computed_from_assumption, insufficient_data

apparent_loss_assumption_bpinteger · optional
non_revenue_water_litersinteger · optional
non_revenue_water_bpinteger · optional
dmas_totalinteger · optional
dmas_computedinteger · optional
dmasarray of IWAWaterBalance · optional
warningsarray of string · optional

Errors 400 · 403 · 404

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/dmas/{id}/water-balance" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "scope": "system",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "status": "computed",
  "system_input_liters": 1,
  "billed_authorized_liters": 1,
  "unbilled_authorized_liters": 1,
  "authorized_consumption_liters": 1342,
  "water_losses_liters": 1,
  "apparent_losses_liters": 1,
  "real_losses_liters": 1,
  "loss_split": "computed_from_assumption",
  "apparent_loss_assumption_bp": 1,
  "non_revenue_water_liters": 1,
  "non_revenue_water_bp": 1,
  "dmas_total": 125000,
  "dmas_computed": 1,
  "dmas": [],
  "warnings": [
    "warning"
  ]
}

Minimum night flow 02

Logs

GET /dmas/{id}/night-flow

Minimum night flow 02:00-04:00 per local night with burst suspicion

Reads the DMA's inflow device measurements and reports, for each local night in the window, the mean flow in litres per second between 02:00 and 04:00, compared with the median of up to seven preceding nights (at least three are needed for a baseline). A night whose excess over the baseline is above threshold_percent is flagged burst_suspected; nights with fewer than two samples are insufficient_data. When the DMA has no inflow meter the report is returned with a warning and no values. The window must be at most 366 days with to after from (400 otherwise); 404 for an unknown DMA.

Parameters

idstring · path · required

Identifier of the district metered area whose inflow device is analysed.

fromstring · query · required

Required start of the window as an RFC 3339 timestamp; the first reported night is the local calendar day containing it.

tostring · query · required

Required end of the window as an RFC 3339 timestamp; it must be after from and no more than 366 days later.

timezonestring · query · optional

IANA time zone name (for example Africa/Maputo) used to place the 02:00-04:00 window and night dates; defaults to UTC, and an unknown zone returns 400.

threshold_percentnumber · query · optional

Positive percentage above the baseline at which a night is flagged as burst suspected; defaults to 30, and zero, negative or non-numeric values return 400.

Returns

200 OK

Show attributes
dma_idstring · optional
device_idstring · optional
timezonestring · optional
threshold_percentnumber · optional
nightsarray of object · optional
Show child attributes
datestring (date) · optional
mean_flow_lpsnumber · optional · nullable
sample_countinteger · optional
baseline_lpsnumber · optional
excess_percentnumber · optional
burst_suspectedboolean · optional
statusstring · optional

one of ok, burst_suspected, insufficient_data

warningsarray of string · optional

Errors 400 · 403 · 404

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/dmas/{id}/night-flow" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
  "timezone": "Africa/Maputo",
  "threshold_percent": 1,
  "nights": [
    {
      "date": "2026-11-19",
      "mean_flow_lps": 1,
      "sample_count": 1,
      "baseline_lps": 1,
      "excess_percent": 1,
      "burst_suspected": true,
      "status": "ok"
    }
  ],
  "warnings": [
    "warning"
  ]
}