Leak allowances

Base URL: $BUSINESS_API

The object

idstring · optional
tenant_idstring · optional
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.

customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

invoice_idstring · optional
invoice_numberstring · optional
statusstring · optional
The object
{
  "id": "lea_2VFECVjsORr40pfwS7Vg6Tp6Ezn",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "invoice_number": "INV-2026-000142",
  "status": "active"
}

Assess an invoice against the policy without saving

Logs

POST /leak-allowances/assess

Runs the policy against the invoice named by invoice_id and returns the outcome without saving anything. When the invoice is eligible, the result holds the consumption, historic average, excess volume and value, and the proposed credit. Otherwise it gives a reason_code: policy_disabled, invoice_not_open, repair_window_expired, cooldown_active, insufficient_history, below_excess_threshold or no_credit_value. It also says whether proof of repair will be required. Needs the business:leak-allowances:read scope.

Returns

200 OK

Show attributes
invoice_idstring · required
eligibleboolean · required
reason_codestring · optional

Stable refusal code for an ineligible invoice; clients translate the value.

one of policy_disabled, invoice_not_open, repair_window_expired, cooldown_active, insufficient_history, below_excess_threshold, no_credit_value

consumption_m3number · required
historic_avg_m3number · optional
excess_m3number · optional
excess_value_centsinteger (int64) · optional
proposed_credit_centsinteger (int64) · optional
currencystring · optional
require_proofboolean · required

Errors 400

Permissions business:leak-allowances:read · Roles: admin, analyst, customer_service, finance, operations, owner, viewer

curl -X POST "$BUSINESS_API/leak-allowances/assess" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 200
{
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "eligible": true,
  "reason_code": "policy_disabled",
  "consumption_m3": 13.42,
  "historic_avg_m3": 1,
  "excess_m3": 1,
  "excess_value_cents": 1342,
  "proposed_credit_cents": 1,
  "currency": "MZN",
  "require_proof": true
}

List leak allowance applications

Logs

GET /leak-allowances

Pages the tenant's leak allowance applications with limit (default 20, max 100) and the after cursor. Filter by status (submitted, inspection_scheduled, inspected, credited or rejected) and account_id. Needs the business:leak-allowances:read scope.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 OK

Show attributes
dataarray of LeakAllowanceApplication · required
Show child attributes
idstring · optional
tenant_idstring · optional
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.

customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

invoice_idstring · optional
invoice_numberstring · optional
statusstring · optional
has_moreboolean · required
next_cursorstring · optional

Permissions business:leak-allowances:read · Roles: admin, analyst, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/leak-allowances" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "lea_2VFECVjsORr40pfwS7Vg6Tp6Ezn",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
      "invoice_number": "INV-2026-000142",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Apply on behalf of a customer

Logs

POST /leak-allowances

Apply on behalf of a customer (multipart: invoice_id, description, proof)

Checks the invoice against the policy and, when it is eligible, creates an application in status submitted with the proposed credit, returned with status 201. Send a multipart form of up to 6 MB with invoice_id, an optional description and a proof file: a PDF, JPEG or PNG of at most 5 MB, required when the policy demands proof. An invoice that already has an open application returns 409, and an ineligible one returns 400 LEAK_ALLOWANCE_INELIGIBLE. Needs the business:leak-allowances:write scope, and the application is recorded in the audit trail.

Returns

200 OK

Permissions business:leak-allowances:read, invoices:read · Roles: admin, analyst, customer_service, finance, owner, viewer

curl -X POST "$BUSINESS_API/leak-allowances" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Get a leak allowance application

Logs

GET /leak-allowances/{id}

Returns one application of the caller's tenant with its account and invoice, its status, the consumption figures and proposed credit, the inspection work order and findings, and the decision with any credit note issued. Returns 404 when the application does not exist in this tenant. Needs the business:leak-allowances:read scope.

Returns

200 OK

Permissions business:leak-allowances:read · Roles: admin, analyst, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/leak-allowances/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Download proof of repair

Logs

GET /leak-allowances/{id}/proof

Streams the proof of repair uploaded with the application as an attachment, using the original file name and a content type taken from its extension (PDF, JPEG or PNG). Returns 404 when the application is not in the caller's tenant, has no proof, or the file cannot be opened. Needs the business:leak-allowances:read scope.

Returns

200 OK

Permissions business:leak-allowances:read · Roles: admin, analyst, customer_service, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/leak-allowances/{id}/proof" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Schedule the inspection work order

Logs

POST /leak-allowances/{id}/inspection

Creates an inspection work order on the application's account and moves the application from submitted to inspection_scheduled, storing the work order ID. Optional notes are appended to the work order's description. Any status other than submitted returns 409. Needs the business:leak-allowances:write scope, and the action is recorded in the audit trail.

Returns

200 OK

Permissions business:leak-allowances:write · Roles: admin, customer_service, operations, owner

curl -X POST "$BUSINESS_API/leak-allowances/{id}/inspection" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Record the inspection result

Logs

POST /leak-allowances/{id}/inspection-result

Stores what the field visit found (leak_confirmed and the required notes), along with the inspector and time, and moves the application to inspected. The application must be in inspection_scheduled (409 otherwise), and empty notes return 400. Only an inspection that confirms a leak can lead to approval. Needs the business:leak-allowances:write scope, and the result is recorded in the audit trail.

Returns

200 OK

Permissions business:leak-allowances:write · Roles: admin, customer_service, operations, owner

curl -X POST "$BUSINESS_API/leak-allowances/{id}/inspection-result" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 200

OK

Approve and issue the credit note

Logs

POST /leak-allowances/{id}/approve

Approve and issue the credit note; the requester cannot approve

Issues a credit note for the proposed credit on the application's invoice, records the optional reason and the adjustment ID, and moves the application to credited. Only an inspected application can be approved (409 otherwise). The inspection must have confirmed a leak, and the policy cooldown is checked again at decision time; either failure returns 400 LEAK_ALLOWANCE_INELIGIBLE. The person who requested the application cannot approve it (403). Needs the business:leak-allowances:approve scope, and the decision is recorded in the audit trail.

Returns

200 OK

Permissions business:leak-allowances:approve · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/leak-allowances/{id}/approve" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Reject an application with a reason

Logs

POST /leak-allowances/{id}/reject

Closes an application that is not yet decided, storing the required reason, the decider and the time, and moving it to rejected. It can be called at any stage before a decision. An application that is already credited or rejected returns 409, and an empty reason returns 400. Needs the business:leak-allowances:approve scope, and the rejection is recorded in the audit trail.

Returns

200 OK

Permissions business:leak-allowances:approve · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/leak-allowances/{id}/reject" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 200

OK