Accounts

Base URL: $CONSUMER_API

The object

idstring · required
tenant_idstring · required
tenant_slugstring · optional

The utility's slug, so a client can brand the account. Omitted when unknown.

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.

permissionsarray of string · optional

Present only in consumer responses and lists the authenticated identity's permissions for this account.

account_numberstring · required
billing_entity_idstring · required
statusstring · required

one of active, suspended, closed

opened_atstring (date-time) · optional
closed_atstring · optional · nullable
The object
{
  "id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "tenant_slug": "tenant slug",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "permissions": [
    "account.read"
  ],
  "account_number": "ACC-2026-000142",
  "billing_entity_id": "bil_2lLuuZnocVf6qrPO4rXsSdtAi95",
  "status": "active",
  "opened_at": "2026-11-19T09:30:00Z",
  "closed_at": "2026-11-19T09:30:00Z"
}

List consumer accounts

Logs

GET /accounts

List accounts explicitly linked to the authenticated consumer

Pages the utility accounts the signed-in person can access through an active membership, across all tenants. Results can be narrowed with the status, customer_id, property_id and q (search) query parameters and use cursor pagination with limit and after.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Accounts authorized for this consumer identity

Show attributes
dataarray of Account · required
Show child attributes
idstring · required
tenant_idstring · required
tenant_slugstring · optional

The utility's slug, so a client can brand the account. Omitted when unknown.

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.

permissionsarray of string · optional

Present only in consumer responses and lists the authenticated identity's permissions for this account.

account_numberstring · required
billing_entity_idstring · required
statusstring · required

one of active, suspended, closed

opened_atstring (date-time) · optional
closed_atstring · optional · nullable
has_moreboolean · required
next_cursorstring · optional
curl -X GET "$CONSUMER_API/accounts" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "tenant_slug": "tenant slug",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
      "property_address": "Av. Julius Nyerere 1420, Maputo",
      "permissions": [
        "account.read"
      ],
      "account_number": "ACC-2026-000142",
      "billing_entity_id": "bil_2lLuuZnocVf6qrPO4rXsSdtAi95",
      "status": "active",
      "opened_at": "2026-11-19T09:30:00Z",
      "closed_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Get consumer account

Logs

GET /accounts/{id}

Get an explicitly linked account in a selected utility tenant

Returns one account the caller holds an active membership on with the account read permission. The tenant is taken from the X-Tenant-ID header or tenant_id query parameter, or worked out from the caller's memberships; 403 is returned when the caller has no access to the account.

Parameters

idstring · path · required

Identifier of the account to return; it must be an account the caller is a member of.

tenant_idstring · query · required

Tenant selector only; the service verifies active account membership.

Returns

200 Account authorized for the authenticated consumer

Show attributes
idstring · required
tenant_idstring · required
tenant_slugstring · optional

The utility's slug, so a client can brand the account. Omitted when unknown.

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.

permissionsarray of string · optional

Present only in consumer responses and lists the authenticated identity's permissions for this account.

account_numberstring · required
billing_entity_idstring · required
statusstring · required

one of active, suspended, closed

opened_atstring (date-time) · optional
closed_atstring · optional · nullable
curl -X GET "$CONSUMER_API/accounts/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "tenant_slug": "tenant slug",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3",
  "property_address": "Av. Julius Nyerere 1420, Maputo",
  "permissions": [
    "account.read"
  ],
  "account_number": "ACC-2026-000142",
  "billing_entity_id": "bil_2lLuuZnocVf6qrPO4rXsSdtAi95",
  "status": "active",
  "opened_at": "2026-11-19T09:30:00Z",
  "closed_at": "2026-11-19T09:30:00Z"
}

Revoke the authenticated consumer's access to an account

Logs

DELETE /accounts/{id}/membership

Ends the caller's own membership on an account, recorded as left by the person; the caller loses access to the account's invoices, payments and readings immediately. The tenant comes from X-Tenant-ID, the tenant_id query parameter or the caller's memberships, and 403 is returned when none can be resolved. Returns 204 on success.

Parameters

idstring · path · required

Identifier of the account the caller wants to leave.

tenant_idstring · query · required

Tenant selector for locating the explicitly linked account.

Returns

204 Consumer membership revoked

curl -X DELETE "$CONSUMER_API/accounts/{id}/membership" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Consumer membership revoked

List delegates and pending invitations

Logs

GET /accounts/{id}/delegates

List delegates and pending invitations (holder only)

Each active delegate also carries display_name, masked_phone and masked_email when known.

Parameters

idstring · path · required

Resource identifier

tenant_idstring · query · optional

Tenant of the account

Returns

200 Delegates

Show attributes
dataarray of object · optional
Show child attributes
idstring · optional
kindstring · optional

one of membership, invitation

identity_idstring · optional
recipientstring · optional
permissionsarray of string · optional
statusstring · optional
curl -X GET "$CONSUMER_API/accounts/{id}/delegates" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "del_2cMzlQ4DheeFbSa75gApbM21xYI",
      "kind": "membership",
      "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
      "recipient": "Ana Matsinhe",
      "permissions": [
        "permission"
      ],
      "status": "active"
    }
  ]
}

Invite a delegate with limited permissions

Logs

POST /accounts/{id}/delegates

Invite a delegate with limited permissions (holder only)

Lets an account holder invite another person by exactly one of phone (at least 9 digits) or email, returning an invitation with a one-time code the invitee redeems through the account-link call. The caller needs the member invite permission on the account; permissions default to account read and invoice read, can only be ones the caller holds, can never include member invite, and always include account read. The invitation expires after expires_in_hours (1 to 720, default 168).

Parameters

idstring · path · required

Resource identifier

tenant_idstring · query · optional

Tenant of the account

Body application/json

phonestring · optional
emailstring · optional
permissionsarray of string · optional
expires_in_hoursinteger · optional

Default 168, maximum 720

account_idstring · optional

Required in bulk requests

Returns

201 Invitation with code

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

channelstring · optional

one of phone, email

recipientstring · optional
permissionsarray of string · optional
statusstring · optional

one of pending, accepted, revoked, expired

codestring · optional

Present only in the creation response, for the staff member who created the invitation; never returned by listings or logged. The code is also delivered to the recipient by e-mail or text message.

expires_atstring (date-time) · optional
curl -X POST "$CONSUMER_API/accounts/{id}/delegates" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+258841234567",
  "email": "ana.matsinhe@example.org",
  "permissions": [
    "permission"
  ],
  "expires_in_hours": 1,
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP"
}'
Response 201
{
  "id": "acc_2ZN2iF5OIjD2mNrQw1HYCxLsgzR",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "channel": "phone",
  "recipient": "Ana Matsinhe",
  "permissions": [
    "permission"
  ],
  "status": "pending",
  "code": "COD-2026-000142",
  "expires_at": "2026-11-19T09:30:00Z"
}

Revoke a delegate membership or pending invitation

Logs

DELETE /accounts/{id}/delegates/{delegate_id}

Lets an account holder with the member invite permission remove a delegate: an invitation id (ivt_) revokes the pending invitation, and a membership id ends that person's access to the account. The holder cannot revoke their own membership through this call, and an id that belongs to another account returns 404. Returns 204 on success.

Parameters

idstring · path · required

Resource identifier

delegate_idstring · path · required

Resource identifier

tenant_idstring · query · optional

Tenant of the account

Returns

204 Revoked

curl -X DELETE "$CONSUMER_API/accounts/{id}/delegates/{delegate_id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Revoked

Download a statement of one of the caller's accounts as PDF

Logs

GET /accounts/{id}/statement.pdf

Renders a PDF account statement for an account linked to the caller, covering from and to (YYYY-MM-DD); to defaults to today and from to one year before to. The locale query parameter (pt-MZ or en-US) picks the language, falling back to the caller's profile locale, and layout=mobile returns a phone-sized layout instead of A4. Returns 400 for a malformed date or from after to, and 403 or 404 when the account is not in the caller's scope.

Parameters

idstring · path · required

Account id

layoutstring · query · optional · default a4

Page format. mobile is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.

one of a4, mobile

fromstring (date) · query · optional

Start of the statement (YYYY-MM-DD); defaults to one year before to

tostring (date) · query · optional

End of the statement (YYYY-MM-DD); defaults to today

Returns

200 PDF document

Errors 403 · 404

curl -X GET "$CONSUMER_API/accounts/{id}/statement.pdf" \
  -H "Authorization: Bearer sk_test_..."
Response 200

PDF document