> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/business-verification/kyb-integration.md).

# KYB integration guide

Integrate KYB from flow selection through applicant submission and review.

This guide connects the KYB API, hosted applicant journey, webhooks, dashboard review, and final case retrieval.

## 1. Select a flow

Use `GET /kyb/flows` to list available country flows. There is no default KYB flow. Pass `flow` when you want to start with a specific country configuration. Omit `flow` to let the applicant choose the business country in the hosted journey.

Review its business-information fields, ownership and control questions, required documents, UBO KYC flow, registry search, and optional website analysis.

## 2. Create the case

Call [`POST /kyb/case`](/docs/business-verification/kyb-create-case.md) from your backend with a stable `refId`:

```json
{
  "refId": "business-7f3d",
  "flow": "66f000000000000000000010"
}
```

Persist the `refId` and returned case ID. Do not log the case token.

## 3. Deliver the hosted journey

Build the Sandbox URL:

```javascript
const url = new URL('/kyb', 'https://web.voveid.net');
url.searchParams.set('authToken', token);
url.searchParams.set('publicKey', 'public_sandbox_replace_me');
url.searchParams.set('environment', 'Sandbox');
```

Deliver it only to the intended applicant. The token expires after 24 hours. If it expires, create a new case or regenerate the token through your approved integration process.

## 4. Applicant completion

The applicant completes the steps configured by the selected flow. These can include:

* Business and registration information.
* Addresses and operating jurisdictions.
* Ownership, control, and related businesses.
* Supporting documents.
* Registry selection.
* UBO invitations and individual KYC.
* Website analysis.

The applicant reviews the entered information and submits the case for review.

## 5. Synchronize status

Verify and deduplicate [KYB webhooks](/docs/business-verification/kyb-webhooks.md). Store every transition, but retrieve the current case before applying a final decision.

| Status        | Meaning                          | Recommended action                                           |
| ------------- | -------------------------------- | ------------------------------------------------------------ |
| `NOT_STARTED` | Link issued; journey not started | Wait or reissue after token expiry                           |
| `IN_PROGRESS` | Applicant is completing steps    | Keep onboarding pending                                      |
| `IN_REVIEW`   | Applicant submitted the case     | Review it in **KYB Cases** in the dashboard                  |
| `COMPLETED`   | Review completed                 | Retrieve details and apply the approved policy               |
| `REJECTED`    | Case rejected                    | Retrieve reason/details and apply the approved recovery path |

## 6. Review the case

Review every submitted case from **KYB Cases** in the VOVE ID dashboard. Compare submitted values with registry/provider evidence and documents. Review UBO results, AML summaries, website analysis, flags, notes, and history. Record the evidence and reason for every request, approval, rejection, or reopen action.

Automated extraction, scores, and external-data matches are supporting evidence, not independent approval authority.

## 7. Retrieve the final resource

```http
GET https://api.voveid.net/kyb/case/business-7f3d/details
x-api-key: vove_sandbox_replace_me
accept: application/json
```

See [Get KYB case details](/docs/business-verification/kyb-case-management.md) for the full response model.

## Recovery

| Problem                     | Action                                                                              |
| --------------------------- | ----------------------------------------------------------------------------------- |
| Token expired               | Create a new case or regenerate the token through your approved integration process |
| Wrong flow selected         | Stop applicant work and confirm the replacement path before recreating              |
| UBO cannot complete KYC     | Preserve references and use the approved support or manual path                     |
| Registry match is ambiguous | Request evidence or escalate; do not select on name alone                           |
| Webhook is delayed          | Retrieve case details and keep onboarding pending                                   |
| Evidence conflicts          | Escalate under your review policy and record the reason                             |