> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brale.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Link Verification Documents

> Link staged KYB document submissions to an account.

Use the playground below to try this endpoint directly, or review the OpenAPI details in the right panel.

Links one or more previously staged document submissions to an account as part of the KYB verification flow. Documents must be [staged first](/api-reference/brale/stage-verification-document) before they can be linked via this endpoint.

During KYB review, Brale may request additional documents. Subscribe to `account.verification.documents_required` to be notified when uploads are needed, or [poll required documents](/api-reference/brale/list-verification-documents). See [Webhook Events](/webhooks/webhook-events#accountverificationdocuments_required).

## Example request

```json theme={null}
{
  "doc_submission_ids": [
    "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "3Ar9BnQCKIrB3SYjKGBzCtFs6XM"
  ]
}
```

## Example response (200)

```json theme={null}
{
  "id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
  "name": "Acme Corp",
  "status": "pending",
  "created": "2026-01-15T10:00:00Z",
  "updated": "2026-06-09T12:00:00Z"
}
```

`status` will remain `"pending"` while Brale reviews the submitted documents. It transitions to `"complete"` once KYB passes or `"rejected"` if declined.

## Error responses

| Status | Cause                                                         |
| ------ | ------------------------------------------------------------- |
| `400`  | `doc_submission_ids` is empty or missing.                     |
| `404`  | Account not found.                                            |
| `422`  | Document upload not allowed for this account's current state. |

## Verification webhooks

Subscribe to verification events so your integration is notified when documents are needed or when KYB completes. Create a subscription with `POST /accounts/{account_id}/webhooks` and include `account.verification.documents_required` in the `events` array. See the [Webhooks overview](/webhooks/overview) for subscription setup and signature verification.

| Event                                     | When it fires                                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------- |
| `account.verification.documents_required` | Brale's KYB review determines one or more documents must be uploaded.                 |
| `account.verification.completed`          | Account verification passes and the account is enabled (`status` becomes `complete`). |

**Typical reactive flow** (documents requested after initial submission):

1. Create the account (`POST /accounts`).
2. Brale reviews the application asynchronously.
3. If additional documents are required, Brale sends `account.verification.documents_required` to your webhook URL.
4. [Stage each required document](/api-reference/brale/stage-verification-document) (use `document_kind` and `person_label` from the webhook payload or list endpoint when present).
5. Link staged submissions with this endpoint.
6. When KYB passes, Brale sends `account.verification.completed`.

## Required scope

`accounts:write`