Connections

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Cut a connection for non-payment

Logs

POST /connections/{id}/disconnect

Cut a connection for non-payment (service_status cut_for_debt)

Requires connections:write in the authenticated utility tenant.

Parameters

idstring · path · required

Identifier of the connection to cut; it must be active or suspended, otherwise the request fails with 400.

Body application/json

reasonstring · optional

Returns

200 Disconnected connection

Errors 400 · 403 · 404

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

curl -X POST "$BUSINESS_API/connections/{id}/disconnect" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200

Disconnected connection

List water service connections

Logs

GET /connections

Returns the tenant's service connections one cursor page at a time (limit defaults to 20, maximum 100). Besides paging, the handler accepts the filters customer_id, property_id, account_id, meter_id, category, status, service_status and q (free-text search that also matches account holders). Requires the connections:read permission in the authenticated utility tenant; a missing permission returns 403.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Service connections in the authenticated utility tenant

Show attributes
dataarray of WaterConnection · required
Show child attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional
total_countinteger · optional

Errors 403

Permissions connections:read · Roles: admin, analyst, customer_service, operations, owner, viewer

curl -X GET "$BUSINESS_API/connections" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
      "property_address": "Av. Julius Nyerere 1420, Maputo",
      "property_holder_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_holder_name": "Ana Matsinhe",
      "meter_serial": "meter serial",
      "category": "residential",
      "diameter_mm": 1,
      "pipe_diameter_mm": 1,
      "pipe_material": "pipe material",
      "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
      "status": "draft",
      "service_status": "pending_install",
      "estimated_cost_cents": 1,
      "currency": "MZN",
      "gps_coordinates": "gps coordinates",
      "address": "Av. Julius Nyerere 1420, Maputo",
      "notes": "Leitura confirmada no local.",
      "rejection_reason": "rejection reason",
      "applied_at": "2026-11-19T09:30:00Z",
      "approved_at": "2026-11-19T09:30:00Z",
      "installed_at": "2026-11-19T09:30:00Z",
      "activated_at": "2026-11-19T09:30:00Z",
      "suspended_at": "2026-11-19T09:30:00Z",
      "retired_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",
  "total_count": 125000
}

Create a new water service connection

Logs

POST /connections

Requires connections:write in the authenticated utility tenant. customer_id and property_id are required; omitted category defaults to residential and omitted or non-positive diameter_mm defaults to 15.

Body application/json

property_idstring · required
customer_idstring · required
categorystring · optional

one of residential, commercial, industrial, institutional, government

diameter_mminteger · optional
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional

Returns

201 Connection created

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403

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

curl -X POST "$BUSINESS_API/connections" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local."
}'
Response 201
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get water service connection details

Logs

GET /connections/{id}

Returns one connection of the authenticated tenant with its application status, service status, and linked customer, property, account and meter. Requires connections:read. Returns 404 when no connection with that ID exists in the tenant.

Parameters

idstring · path · required

Identifier of the connection in the authenticated tenant.

Returns

200 Service connection details

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 403 · 404

Permissions connections:read · Roles: admin, analyst, customer_service, operations, owner, viewer

curl -X GET "$BUSINESS_API/connections/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Update water service connection details

Logs

PATCH /connections/{id}

Requires connections:write in the authenticated utility tenant.

Parameters

idstring · path · required

Identifier of the connection to update in the authenticated tenant.

Body application/json

pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
meter_idstring · optional
account_idstring · optional
notesstring · optional
gps_coordinatesstring · optional

Returns

200 Updated connection

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404

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

curl -X PATCH "$BUSINESS_API/connections/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "notes": "Leitura confirmada no local.",
  "gps_coordinates": "gps coordinates"
}'
Response 200
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Approve or reject a water service connection application

Logs

POST /connections/{id}/review

Requires connections:write in the authenticated utility tenant.

Parameters

idstring · path · required

Identifier of the connection application to review; it must be in the submitted or inspecting status, otherwise the request fails with 400.

Body application/json

approvedboolean · required
estimated_cost_centsinteger (int64) · optional
currencystring · optional
rejection_reasonstring · optional
notesstring · optional

Returns

200 Reviewed connection application

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404

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

curl -X POST "$BUSINESS_API/connections/{id}/review" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "approved": true,
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "rejection_reason": "rejection reason",
  "notes": "Leitura confirmada no local."
}'
Response 200
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Schedule installation of an approved connection

Logs

POST /connections/{id}/schedule-install

Requires connections:write in the authenticated utility tenant.

Parameters

idstring · path · required

Identifier of the connection to schedule; it must be in the approved status, otherwise the request fails with 400.

Returns

200 Installation scheduled

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404

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

curl -X POST "$BUSINESS_API/connections/{id}/schedule-install" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Complete installation and activate a connection

Logs

POST /connections/{id}/activate

Requires connections:write in the authenticated utility tenant.

Parameters

idstring · path · required

Identifier of the connection to activate; it must be in the approved or installing status, otherwise the request fails with 400.

Body application/json

meter_idstring · optional
account_idstring · optional

Returns

200 Activated connection

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404

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

curl -X POST "$BUSINESS_API/connections/{id}/activate" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP"
}'
Response 200
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Suspend an active connection

Logs

POST /connections/{id}/suspend

Requires connections:write in the authenticated utility tenant.

Parameters

idstring · path · required

Identifier of the connection to suspend; it must be active, otherwise the request fails with 400.

Body application/json

reasonstring · optional

Returns

200 Suspended connection

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404

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

curl -X POST "$BUSINESS_API/connections/{id}/suspend" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Restore a suspended or disconnected connection

Logs

POST /connections/{id}/reconnect

Requires connections:write in the authenticated utility tenant.

Parameters

idstring · path · required

Identifier of the connection to restore; it must be suspended or disconnected, otherwise the request fails with 400.

Returns

200 Reconnected service

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404

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

curl -X POST "$BUSINESS_API/connections/{id}/reconnect" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Retire a water service connection

Logs

POST /connections/{id}/retire

Requires connections:write in the authenticated utility tenant.

Parameters

idstring · path · required

Identifier of the connection to retire; a connection that is already retired returns 400.

Body application/json

reasonstring · optional

Returns

200 Retired connection

Show attributes
idstring · required
tenant_idstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

property_idstring · required
property_addressstring · optional

Address line of the referenced property. Omitted when unknown.

property_holder_namestring · optional

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

meter_idstring · optional
meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

meter_serialstring · optional
categorystring · required

one of residential, commercial, industrial, institutional, government

diameter_mminteger · required
pipe_diameter_mminteger · optional
pipe_materialstring · optional
pressure_zone_idstring · optional
statusstring · required

one of draft, submitted, inspecting, approved, rejected, installing, active, suspended, disconnected, retired

service_statusstring · required

one of pending_install, active, cut_for_debt, suspended_customer_request, abandoned

estimated_cost_centsinteger (int64) · required
currencystring · required
gps_coordinatesstring · optional
addressstring · optional
notesstring · optional
rejection_reasonstring · optional
applied_atstring (date-time) · required
approved_atstring (date-time) · optional
installed_atstring (date-time) · optional
activated_atstring (date-time) · optional
suspended_atstring (date-time) · optional
retired_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 403 · 404

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

curl -X POST "$BUSINESS_API/connections/{id}/retire" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200
{
  "id": "wat_2E6F9Umzh4yLHuavzusVNMqJHiS",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "property_holder_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_holder_name": "Ana Matsinhe",
  "meter_serial": "meter serial",
  "category": "residential",
  "diameter_mm": 1,
  "pipe_diameter_mm": 1,
  "pipe_material": "pipe material",
  "pressure_zone_id": "pre_2Ww5XCYxHs6jv2K53SI3fu47RkI",
  "status": "draft",
  "service_status": "pending_install",
  "estimated_cost_cents": 1,
  "currency": "MZN",
  "gps_coordinates": "gps coordinates",
  "address": "Av. Julius Nyerere 1420, Maputo",
  "notes": "Leitura confirmada no local.",
  "rejection_reason": "rejection reason",
  "applied_at": "2026-11-19T09:30:00Z",
  "approved_at": "2026-11-19T09:30:00Z",
  "installed_at": "2026-11-19T09:30:00Z",
  "activated_at": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "retired_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get the metadata of a connection

Logs

GET /connections/{id}/metadata

Returns the free-form key-value metadata the tenant has stored on a connection, as a resource_type, resource_id and metadata object. A connection without metadata returns an empty map. Requires business:metadata:read; returns 404 when the connection does not exist in the tenant.

Parameters

idstring · path · required

Identifier of the connection whose metadata is read (at most 120 characters).

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/connections/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /connections/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the supplied keys into the connection's existing metadata and returns the full result; keys not in the request stay unchanged. A request may set at most 50 keys, each key at most 40 characters with no square brackets or control characters, and each value at most 500 characters; a resource may hold at most 50 keys in total. Requires business:metadata:write; invalid keys or values return 400 listing each offending field, and an unknown connection returns 404.

Parameters

idstring · path · required

Identifier of the connection whose metadata is merged (at most 120 characters).

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/connections/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}