Skip to navigation

Close this tenant's access to the account

Removes this tenant’s access to the account. The HTTP response is the same whether another CorpX tenant still operates the bank account or this tenant is the last one: the caller cannot tell.

Humans need tenant_manager or admin. Credentials need the accounts.close scope (legacy api2/write still passes). A viewer cannot close.

The row is not deleted. It becomes status=closed with status_source=tenant_close. Already closed in this tenant returns the same 200 without a second closure request.

When this tenant is the last one still operating the account, the closure goes to the settlement bank, which only accepts a zeroed account: no available balance and no locked balance. The raw settlement-bank balance is checked first. A non-zero available balance returns 422 account_has_balance; an available balance of zero with a locked balance (for example a MED hold) returns 422 account_has_locked_balance. Both leave the row active and carry the raw balance. With the balance zeroed, the account must also have no PIX keys. Any key returns 422 account_has_pix_keys with keys listing only the key type, never the key value. Delete the keys and call again. With the balance zeroed and no keys, the closure is requested from the settlement bank and the row is closed in the same call. The bank account itself is closed when the settlement bank processes the request; the 200 does not say when.

Binding to another tenant’s account, a missing account, or a suspended row is always 404 account_not_found — never 403 tenant_mismatch.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

Response

This tenant lost access. The message is identical on both internal paths.
accountIdstring
messagestring

Errors

403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
503
Service Unavailable Error