Accounts

Base URL: $BUSINESS_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 service and billing accounts for the utility tenant

Logs

GET /accounts

Lists the service accounts of the caller's workspace, optionally filtered by customer, property, status and a free-text q search. Results are paginated with limit (default 20, maximum 100) and the after cursor; a negative or non-numeric limit returns 400. Requires the business:accounts:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

qstring · query · optional

Resource-specific text search.

customer_idstring · query · optional

Customer identifier; when set, only accounts belonging to that customer are returned.

property_idstring · query · optional

Property identifier; when set, only accounts opened for that property are returned.

statusstring · query · optional

Account status to keep: active, suspended or closed; when omitted, accounts in every status are returned.

one of active, suspended, closed

Returns

200 Utility accounts

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

Permissions business:accounts:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_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"
}

Open a billing/service account

Logs

POST /accounts

Opens a service account for a customer at one of that customer's properties in the caller's workspace. Both customer_id and property_id are required (400 otherwise); either one missing returns 404, and a property that belongs to a different customer returns 409. The account starts active and receives the next number from the workspace's gap-free account number series. Requires the business:accounts:create permission.

Body application/json

customer_idstring · required
property_idstring · required

Returns

201 Account opened

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

Permissions business:accounts:create · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/accounts" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "property_id": "prp_2ZbuIh1k2RvWMVPQCJD2yPrsOJ3"
}'
Response 201
{
  "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"
}

Get an account in the authenticated utility tenant

Logs

GET /accounts/{id}

Returns one service account of the caller's workspace, including its number, customer, property, billing entity, status and opening date. An account from another workspace returns 404. Requires the business:accounts:read permission.

Parameters

idstring · path · required

Identifier of the service account to return.

Returns

200 Utility account

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

Permissions business:accounts:read · Roles: admin, analyst, billing_clerk, customer_service, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_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"
}

List identities linked to an account

Logs

GET /accounts/{account_id}/memberships

Each membership also carries display_name, masked_phone and masked_email when the identity is known; contact details are masked.

Parameters

account_idstring · path · required

Resource identifier

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

identity_idstring · query · optional

Filter by identity

include_revokedstring · query · optional

Set to true to include revoked memberships

Returns

200 Memberships

Permissions business:accounts:memberships:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/accounts/{account_id}/memberships" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Memberships

Grant a consumer explicit account permissions

Logs

POST /accounts/{account_id}/memberships

Links an identity directly to an account with the given permissions, without an invitation. identity_id and at least one valid permission are required, and expires_at, when set, must be in the future (400 otherwise); the account must exist in the caller's workspace (404). The membership is a holder membership when the permissions include inviting members, and a delegate membership otherwise. Requires the business:accounts:memberships:create permission.

Parameters

account_idstring · path · required

Identifier of the service account in the caller's workspace that the identity is linked to.

Body application/json

identity_idstring · required
permissionsarray of string · required
expires_atstring · optional · nullable

Returns

201 Account membership created

Permissions business:accounts:memberships:create · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/accounts/{account_id}/memberships" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
  "permissions": [
    "account.read"
  ],
  "expires_at": "2026-11-19T09:30:00Z"
}'
Response 201

Account membership created

Revoke a consumer's account membership

Logs

DELETE /accounts/{account_id}/memberships/{identity_id}

Ends an identity's membership on an account. Staff of the workspace need the business:accounts:memberships:revoke permission; a person may also remove their own membership, which is recorded as left by the person rather than revoked by the utility. Returns 404 when no active membership matches; answers 204.

Parameters

account_idstring · path · required

Identifier of the service account the membership belongs to.

identity_idstring · path · required

Identifier of the identity (person) whose membership on the account is ended.

Returns

204 Membership revoked

Permissions business:accounts:memberships:revoke · Roles: admin, customer_service, owner

curl -X DELETE "$BUSINESS_API/accounts/{account_id}/memberships/{identity_id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Membership revoked

List invitations with derived status

Logs

GET /accounts/{account_id}/invitations

Lists the invitations issued for one account, each with a status derived at request time (for example pending, accepted, revoked or expired). Results are paginated with limit (default 20, maximum 100) and the after cursor. Returns 404 when the account is not in the caller's workspace; requires the business:accounts:invitations:read permission.

Parameters

account_idstring · path · required

Resource identifier

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Invitations

Show attributes
dataarray of AccountInvitation · optional
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.

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
has_moreboolean · optional
next_cursorstring · optional

Permissions business:accounts:invitations:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/accounts/{account_id}/invitations" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a short, expiring, single-use invitation code

Logs

POST /accounts/{account_id}/invitations

Issues an 8-character, single-use invitation code that lets a person link themselves to this account, and sends it to exactly one phone (at least 9 digits) or e-mail address. Permissions default to the holder permissions; expires_in_hours defaults to 168 (7 days) and must be between 1 and 720. Returns 503 when the recipient's channel has no delivery provider; if sending fails the invitation is revoked and the error returned. Requires the business:accounts:invitations:create permission.

Parameters

account_idstring · path · required

Resource identifier

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 including its code, shown only once to the staff member who created it. The code is also sent to the recipient by e-mail or text message. Outside development with no provider for the recipient, the request fails with 503.

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

Errors 503

Permissions business:accounts:invitations:create · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/accounts/{account_id}/invitations" \
  -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 pending invitation

Logs

DELETE /accounts/{account_id}/invitations/{invitation_id}

Withdraws an invitation so its code can no longer be redeemed. Only invitations that are still pending can be revoked; an accepted or already revoked invitation returns 409, and an invitation that belongs to another account returns 404. Answers 204; requires the business:accounts:invitations:revoke permission.

Parameters

account_idstring · path · required

Resource identifier

invitation_idstring · path · required

Resource identifier

Returns

204 Revoked

Permissions business:accounts:invitations:revoke · Roles: admin, customer_service, owner

curl -X DELETE "$BUSINESS_API/accounts/{account_id}/invitations/{invitation_id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Revoked

Get the metadata of a account

Logs

GET /accounts/{id}/metadata

Returns the custom key-value metadata stored on a service account, as a map of string keys to string values. The account must exist in the caller's workspace, otherwise 404. Requires the business:metadata:read permission.

Parameters

idstring · path · required

Identifier of the service account whose metadata is returned (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/accounts/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /accounts/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the given keys into the account's metadata and returns the full resulting map: keys sent with a value are added or replaced, keys sent with an empty string are deleted, and keys not mentioned are kept. At most 50 keys may be sent at once; keys must be non-blank, at most 40 characters, without square brackets or control characters, and values at most 500 characters, otherwise 400 lists each invalid field. The account must exist in the caller's workspace (404 otherwise); requires the business:metadata:write permission.

Parameters

idstring · path · required

Identifier of the service account whose metadata is changed (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/accounts/{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"
  }
}

Get account credit balance and grants

Logs

GET /accounts/{id}/credits

grants lists every grant of the account, pending_approval and rejected ones included, newest first; the totals count only active grants with money left.

Parameters

idstring · path · required

Identifier of the service account in the caller's workspace whose credit balance is returned.

Returns

200 Account credit balance summary

Show attributes
account_idstring · required
currencystring · required
cash_minorinteger (int64) · required
granted_minorinteger (int64) · required
promotional_minorinteger (int64) · required
next_expirystring (date-time) · optional
grantsarray of CreditGrant · required
Show child attributes
idstring · required
tenant_idstring · required
account_idstring · required
campaign_idstring · optional
fundingstring · required

one of cash, granted

sourcestring · required
amount_minorinteger (int64) · required
remaining_minorinteger (int64) · required
currencystring · required
applies_toarray of string · optional
charge_kindsarray of string · optional
expires_atstring (date-time) · optional
statusstring · required

one of pending_approval, active, exhausted, expired, rejected

proposed_bystring · optional
approved_bystring · optional
rejection_reasonstring · optional
reasonstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions invoices:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/accounts/{id}/credits" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "currency": "MZN",
  "cash_minor": 1,
  "granted_minor": 1,
  "promotional_minor": 1,
  "next_expiry": "2026-11-19T09:30:00Z",
  "grants": [
    {
      "id": "cre_2cmf76oNbMmjnic9ZsClLOiDDwu",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "campaign_id": "cam_2WQBFWMJR6y3LeY1tCERReuZREk",
      "funding": "cash",
      "source": "source",
      "amount_minor": 125000,
      "remaining_minor": 1,
      "currency": "MZN",
      "applies_to": [
        "2026-11-19"
      ],
      "charge_kinds": [
        "charge kind"
      ],
      "expires_at": "2026-11-19T09:30:00Z",
      "status": "pending_approval",
      "proposed_by": "proposed by",
      "approved_by": "approved by",
      "rejection_reason": "rejection reason",
      "reason": "Leitura confirmada no local.",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}