> 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-create-case.md).

# Create a KYB case

Create a KYB case and issue a short-lived hosted verification link.

Creates or resumes a business-verification case for a stable `refId`.

```http
POST https://api.voveid.net/kyb/case
x-api-key: vove_sandbox_replace_me
content-type: application/json
```

Call this endpoint from your backend. The response contains a case token that you deliver only to the intended business applicant.

## Request

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

### Body parameters

| Field   | Type   | Required | Default | Description                                                                                                              |
| ------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `refId` | string | Yes      | —       | Stable business identifier from your system                                                                              |
| `flow`  | string | No       | —       | KYB flow identifier. Supply it to use a specific country flow; omit it to let the applicant choose the business country. |

There is no default KYB flow. When `flow` is omitted, the hosted journey lets the applicant choose the business country. Supply `flow` only when you want to start with a specific country flow. The create request accepts only `refId` and optional `flow`; the applicant supplies business data inside the hosted case flow.

### TypeScript shape

```typescript
type CreateKybCaseRequest = {
  refId: string;
  flow?: string;
};
```

## Response

```json
{
  "kybCase": {
    "_id": "66f000000000000000000011",
    "refId": "business-7f3d",
    "status": "NOT_STARTED",
    "flow": "66f000000000000000000010"
  },
  "token": "eyJ...redacted"
}
```

### Response fields

| Field            | Type             | Description                                                |
| ---------------- | ---------------- | ---------------------------------------------------------- |
| `kybCase._id`    | string           | VOVE ID case identifier                                    |
| `kybCase.refId`  | string           | Your stable business identifier                            |
| `kybCase.status` | string           | Initial status, normally `NOT_STARTED`                     |
| `kybCase.flow`   | string, optional | Country-specific KYB flow identifier when one was selected |
| `token`          | string           | Short-lived token for the hosted business journey          |

```typescript
type KybCaseStatus =
  | 'NOT_STARTED'
  | 'IN_PROGRESS'
  | 'IN_REVIEW'
  | 'COMPLETED'
  | 'REJECTED';

type CreateKybCaseResponse = {
  kybCase: {
    _id: string;
    refId: string;
    status: KybCaseStatus | string;
    flow?: string;
    [field: string]: unknown;
  };
  token: string;
};
```

The token is valid for 24 hours. If it expires, create a new case or regenerate the token through your approved integration process.

## cURL example

```bash
curl --request POST 'https://api.voveid.net/kyb/case' \
  --header 'content-type: application/json' \
  --header 'x-api-key: vove_sandbox_replace_me' \
  --data '{
    "refId": "business-7f3d",
    "flow": "66f000000000000000000010"
  }'
```

## Generate the hosted link

Use the `/kyb` path for the matching environment:

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

Deliver this link over TLS or another authenticated channel bound to the intended applicant. Do not log the token, put it in analytics, or reuse it for another business.

## Errors

| Status | Typical cause                                        | Action                             |
| ------ | ---------------------------------------------------- | ---------------------------------- |
| `400`  | Invalid `refId`, flow, or request field              | Correct the request                |
| `401`  | Missing or invalid private API key                   | Check backend secret configuration |
| `404`  | The selected flow does not exist in this environment | Discover the available flows again |

## Next steps

1. Persist the case ID and `refId`.
2. Deliver the hosted link.
3. Receive [KYB webhooks](/docs/business-verification/kyb-webhooks.md).
4. Review the submitted case in **KYB Cases** in the VOVE ID dashboard.
5. Retrieve [case details](/docs/business-verification/kyb-case-management.md) before applying your final decision.