PT EN

Contas

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
tenant_slugstring · opcional

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

customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

property_idstring · obrigatório
property_addressstring · opcional

Address line of the referenced property. Omitted when unknown.

permissionsarray of string · opcional

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

account_numberstring · obrigatório
billing_entity_idstring · obrigatório
statusstring · obrigatório

um de active, suspended, closed

opened_atstring (date-time) · opcional
closed_atstring · opcional · anulável
O objecto
{
  "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"
}

Listar contas

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

qstring · consulta · opcional

Resource-specific text search.

customer_idstring · consulta · opcional

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

property_idstring · consulta · opcional

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

statusstring · consulta · opcional

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

um de active, suspended, closed

Devolve

200 Utility accounts

Mostrar atributos
dataarray of Account · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
tenant_slugstring · opcional

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

customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

property_idstring · obrigatório
property_addressstring · opcional

Address line of the referenced property. Omitted when unknown.

permissionsarray of string · opcional

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

account_numberstring · obrigatório
billing_entity_idstring · obrigatório
statusstring · obrigatório

um de active, suspended, closed

opened_atstring (date-time) · opcional
closed_atstring · opcional · anulável
has_moreboolean · obrigatório
next_cursorstring · opcional

Permissões business:accounts:read · Funções: 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_..."
Resposta 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"
}

Abrir uma conta

Registos

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.

Corpo application/json

customer_idstring · obrigatório
property_idstring · obrigatório

Devolve

201 Account opened

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
tenant_slugstring · opcional

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

customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

property_idstring · obrigatório
property_addressstring · opcional

Address line of the referenced property. Omitted when unknown.

permissionsarray of string · opcional

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

account_numberstring · obrigatório
billing_entity_idstring · obrigatório
statusstring · obrigatório

um de active, suspended, closed

opened_atstring (date-time) · opcional
closed_atstring · opcional · anulável

Permissões business:accounts:create · Funções: 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"
}'
Resposta 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"
}

Obter uma conta

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Identifier of the service account to return.

Devolve

200 Utility account

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
tenant_slugstring · opcional

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

customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

property_idstring · obrigatório
property_addressstring · opcional

Address line of the referenced property. Omitted when unknown.

permissionsarray of string · opcional

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

account_numberstring · obrigatório
billing_entity_idstring · obrigatório
statusstring · obrigatório

um de active, suspended, closed

opened_atstring (date-time) · opcional
closed_atstring · opcional · anulável

Permissões business:accounts:read · Funções: 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_..."
Resposta 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"
}

Listar os acessos a uma conta

Registos

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.

Parâmetros

account_idstring · caminho · obrigatório

Resource identifier

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

identity_idstring · consulta · opcional

Filter by identity

include_revokedstring · consulta · opcional

Set to true to include revoked memberships

Devolve

200 Memberships

Permissões business:accounts:memberships:read · Funções: admin, customer_service, owner

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

Memberships

Dar acesso a uma conta

Registos

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.

Parâmetros

account_idstring · caminho · obrigatório

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

Corpo application/json

identity_idstring · obrigatório
permissionsarray of string · obrigatório
expires_atstring · opcional · anulável

Devolve

201 Account membership created

Permissões business:accounts:memberships:create · Funções: 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"
}'
Resposta 201

Account membership created

Retirar o acesso a uma conta

Registos

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.

Parâmetros

account_idstring · caminho · obrigatório

Identifier of the service account the membership belongs to.

identity_idstring · caminho · obrigatório

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

Devolve

204 Membership revoked

Permissões business:accounts:memberships:revoke · Funções: admin, customer_service, owner

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

Membership revoked

Listar convites de uma conta

Registos

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.

Parâmetros

account_idstring · caminho · obrigatório

Resource identifier

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Invitations

Mostrar atributos
dataarray of AccountInvitation · opcional
Mostrar atributos filhos
idstring · opcional
tenant_idstring · opcional
account_idstring · opcional
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

channelstring · opcional

um de phone, email

recipientstring · opcional
permissionsarray of string · opcional
statusstring · opcional

um de pending, accepted, revoked, expired

codestring · opcional

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) · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Permissões business:accounts:invitations:read · Funções: admin, customer_service, owner

curl -X GET "$BUSINESS_API/accounts/{account_id}/invitations" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Criar um código de convite

Registos

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.

Parâmetros

account_idstring · caminho · obrigatório

Resource identifier

Corpo application/json

phonestring · opcional
emailstring · opcional
permissionsarray of string · opcional
expires_in_hoursinteger · opcional

Default 168, maximum 720

account_idstring · opcional

Required in bulk requests

Devolve

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.

Mostrar atributos
idstring · opcional
tenant_idstring · opcional
account_idstring · opcional
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

channelstring · opcional

um de phone, email

recipientstring · opcional
permissionsarray of string · opcional
statusstring · opcional

um de pending, accepted, revoked, expired

codestring · opcional

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) · opcional

Erros 503

Permissões business:accounts:invitations:create · Funções: 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"
}'
Resposta 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"
}

Revogar um convite

Registos

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.

Parâmetros

account_idstring · caminho · obrigatório

Resource identifier

invitation_idstring · caminho · obrigatório

Resource identifier

Devolve

204 Revoked

Permissões business:accounts:invitations:revoke · Funções: admin, customer_service, owner

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

Revoked

Obter os metadados de uma conta

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Identifier of the service account whose metadata is returned (at most 120 characters).

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

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

Actualizar os metadados de uma conta

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Identifier of the service account whose metadata is changed (at most 120 characters).

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

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

Obter o saldo de créditos de uma conta

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Account credit balance summary

Mostrar atributos
account_idstring · obrigatório
currencystring · obrigatório
cash_minorinteger (int64) · obrigatório
granted_minorinteger (int64) · obrigatório
promotional_minorinteger (int64) · obrigatório
next_expirystring (date-time) · opcional
grantsarray of CreditGrant · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
account_idstring · obrigatório
campaign_idstring · opcional
fundingstring · obrigatório

um de cash, granted

sourcestring · obrigatório
amount_minorinteger (int64) · obrigatório
remaining_minorinteger (int64) · obrigatório
currencystring · obrigatório
applies_toarray of string · opcional
charge_kindsarray of string · opcional
expires_atstring (date-time) · opcional
statusstring · obrigatório

um de pending_approval, active, exhausted, expired, rejected

proposed_bystring · opcional
approved_bystring · opcional
rejection_reasonstring · opcional
reasonstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões invoices:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/accounts/{id}/credits" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
    }
  ]
}