Soft-delete a business customer (sets is_active=False).
Does not touch kyb_status or the verification provider applicant. Deactivated
businesses are hidden from the default GET /businesses response
unless the caller passes include_inactive=true. Idempotent.
require_client_permissions enforces allowed_roles only for
client_user actors; the explicit role guard below also rejects
client_api callers whose credential role is not Owner.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Soft-deletes a business customer by setting is_active to false. This does not change the company's kyb_status or affect any verification already on file; it only hides the record from the default business listing. Returns the updated business customer.
The operation is idempotent — deactivating an already-inactive business is a no-op that returns the current record unchanged, and no new audit entry is written.
Deactivated businesses are excluded from GET /api/v1/kyb/businesses by default. To include them in that listing, pass include_inactive=true. A deactivated business can be brought back with POST /api/v1/kyb/businesses/{business_id}/activate.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - The caller must hold the
kyb.businesses.writepermission. - Only the OWNER role may deactivate a business. No other role is permitted, including for API-token callers.
Path parameters
| Name | In | Required | Description |
|---|---|---|---|
business_id | path | yes | The ID of the business customer to deactivate. Must belong to your client. |
Request body
| Field | Type | Constraints | Description |
|---|---|---|---|
reason | string | required, 10–500 characters | Operational reason recorded in the audit log. The minimum length ensures the audit trail captures meaningful context. |
Response
200 OK returns the BusinessCustomerResponse for the business with is_active set to false. All other fields (kyb_status, verification_mode, verification details, etc.) are unchanged.
Error responses
| Status | When |
|---|---|
404 | No business customer with this business_id exists under your client |
422 | Request body failed validation (reason missing, shorter than 10 characters, or longer than 500) |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.