Account link requests

Base URL: $BUSINESS_API

The object

idstring · optional
tenant_idstring · optional
account_idstring · optional
account_holder_namestring · optional

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

identity_idstring · optional
account_numberstring · optional
phonestring · optional
statusstring · optional

one of pending, approved, rejected, cancelled

reasonstring · optional
The object
{
  "id": "acc_2EuRxSyNd8kv1G6pXooBRwCv7KW",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_holder_name": "Ana Matsinhe",
  "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
  "account_number": "ACC-2026-000142",
  "phone": "+258841234567",
  "status": "pending",
  "reason": "Leitura confirmada no local."
}

Queue of consumer link requests

Logs

GET /account-link-requests

Returns the workspace's queue of requests from people asking to be linked to a customer account. By default only pending requests are listed; status accepts pending, approved, rejected or cancelled. Results are paginated with limit (default 20, maximum 100) and the after cursor. Requires the business:accounts:link-requests:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

statusstring · query · optional

pending (default), approved or rejected

Returns

200 Link requests

Show attributes
dataarray of AccountLinkRequest · optional
Show child attributes
idstring · optional
tenant_idstring · optional
account_idstring · optional
account_holder_namestring · optional

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

identity_idstring · optional
account_numberstring · optional
phonestring · optional
statusstring · optional

one of pending, approved, rejected, cancelled

reasonstring · optional
has_moreboolean · optional
next_cursorstring · optional

Permissions business:accounts:link-requests:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/account-link-requests" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "acc_2EuRxSyNd8kv1G6pXooBRwCv7KW",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_holder_name": "Ana Matsinhe",
      "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
      "account_number": "ACC-2026-000142",
      "phone": "+258841234567",
      "status": "pending",
      "reason": "Leitura confirmada no local."
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Approve a link request, creating the membership

Logs

POST /account-link-requests/{id}/approve

Approves a pending link request and, in the same change, gives the requesting person an active holder membership on the account with the standard holder permissions. Returns the updated request. A request already decided returns 409, and one from another workspace returns 404. Requires the business:accounts:link-requests:decide permission.

Parameters

idstring · path · required

Resource identifier

Returns

200 Request

Show attributes
idstring · optional
tenant_idstring · optional
account_idstring · optional
account_holder_namestring · optional

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

identity_idstring · optional
account_numberstring · optional
phonestring · optional
statusstring · optional

one of pending, approved, rejected, cancelled

reasonstring · optional

Permissions business:accounts:link-requests:decide · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/account-link-requests/{id}/approve" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "acc_2EuRxSyNd8kv1G6pXooBRwCv7KW",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_holder_name": "Ana Matsinhe",
  "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
  "account_number": "ACC-2026-000142",
  "phone": "+258841234567",
  "status": "pending",
  "reason": "Leitura confirmada no local."
}

Reject a link request

Logs

POST /account-link-requests/{id}/reject

Refuses a resident's pending request to link a service account to their identity, recording the reason, the staff member who decided and the time. No account membership is created, and the request keeps the reason so the resident can see why. A missing reason returns 400; a request of another utility, or one without a matched account, returns 404. Requires business:accounts:link-requests:decide.

Parameters

idstring · path · required

Resource identifier

Body application/json

reasonstring · required

Returns

200 Request

Show attributes
idstring · optional
tenant_idstring · optional
account_idstring · optional
account_holder_namestring · optional

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

identity_idstring · optional
account_numberstring · optional
phonestring · optional
statusstring · optional

one of pending, approved, rejected, cancelled

reasonstring · optional

Permissions business:accounts:link-requests:decide · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/account-link-requests/{id}/reject" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200
{
  "id": "acc_2EuRxSyNd8kv1G6pXooBRwCv7KW",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_holder_name": "Ana Matsinhe",
  "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
  "account_number": "ACC-2026-000142",
  "phone": "+258841234567",
  "status": "pending",
  "reason": "Leitura confirmada no local."
}