# Create KYB Case

### Creating a KYB Verification Case

#### Overview

Creating a KYB case is the first step in verifying a business entity. When you create a case, VOVE ID generates a secure verification token that you can use to form a verification link for your business customer. The business then uses this link to access the verification portal and complete the required steps.

#### Endpoint

* **Method**: `POST`
* **URL**: `/kyb/case`
* **Authentication**: Required (x-api-key header)

### Request

#### Headers

```http
Content-Type: application/json
x-api-key: YOUR_API_KEY
```

#### Request Body

```json
{
  "refId": "unique-business-ref-12345",
  "flow": "64a1b2c3d4e5f6g7h8i9j0k1",
  "country": "GB",
  "country_state": "England"
}
```

#### Parameters

| Parameter       | Type   | Required | Description                                                                                                               |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `flow`          | string | No       | The KYB flow ID that defines the verification requirements for this business                                              |
| `refId`         | string | Yes      | Your internal reference ID for this business. This field is currently required and is used to retrieve case status later. |
| `country`       | string | No       | Optional country code associated with the case                                                                            |
| `country_state` | string | No       | Optional state or region associated with the case                                                                         |

> `POST /kyb/case` currently creates the case record and returns the hosted KYB session token. It does not currently accept `businessName` or `formData` for pre-populating the hosted flow.

### Response

#### Success Response (200 OK)

```json
{
  "kybCase": {
    "_id": "65f1a2b3c4d5e6f7g8h9i0j1",
    "refId": "unique-business-ref-12345",
    "status": "NOT_STARTED",
    "flow": "64a1b2c3d4e5f6g7h8i9j0k1"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Response Fields

| Field            | Type   | Description                                                                       |
| ---------------- | ------ | --------------------------------------------------------------------------------- |
| `kybCase._id`    | string | Unique identifier for this KYB case                                               |
| `kybCase.refId`  | string | Your reference ID for this case                                                   |
| `kybCase.status` | string | Current status: "NOT\_STARTED" initially                                          |
| `kybCase.flow`   | string | The ID of the KYB flow configuration being used                                   |
| `token`          | string | JWT token for the business to access the verification portal (valid for 24 hours) |

### Generating the Verification Link

Once you receive the response with the token, construct the verification link for your business customer:

```javascript
const verificationLink = `https://web.voveid.com/kyb/?authToken=${token}&publicKey=${YOUR_PUBLIC_KEY}&environment=Production`;
```

**Parameters:**

* `authToken` - The token received from the create case response
* `publicKey` - Your organization's public key (found in the VOVE ID dashboard)
* `environment` - Either "Production" or "Sandbox"

**Example Link:**

```
https://web.voveid.com/kyb/?authToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&publicKey=pk_live_abc123&environment=Production
```

### Example Request

#### Using cURL

```bash
curl -X POST https://api.voveid.com/kyb/case \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "refId": "unique-business-ref-12345",
    "flow": "64a1b2c3d4e5f6g7h8i9j0k1",
    "country": "GB"
  }'
```

### Best Practices

#### Reference ID Management

* **Use Your Own refId**: Provide your internal business ID as the `refId` to easily correlate KYB cases with your database records
* **Store the refId**: Persist the same `refId` in your database for future status lookups and reconciliation
* **Unique per Business**: Each business entity should have a unique refId

#### Pre-filling Data

* **Create First, Then Collect Data**: `POST /kyb/case` only creates the case and returns the KYB session token
* **Use the Hosted Flow for Business Details**: Business details are collected once the customer opens the KYB verification flow

#### Token Security

* **Never Expose in Frontend**: Generate the verification link on your backend server
* **Secure Transmission**: Send the link to the business customer via secure channels (email, SMS, encrypted messaging)
* **Token Expiry**: Tokens are valid for 24 hours. If expired, create a new case or regenerate the token

#### Flow Selection

* **Country-Specific Flows**: Use flows configured for the business's country of registration
* **Compliance Requirements**: Choose flows that match your compliance and risk assessment needs
* **Flow Discovery**: Use `GET /kyb/flows` to list all KYB flows available to your organization
* **Default Flows**: Use `GET /kyb/flows/default` to discover the default KYB flows available to your organization

See [KYB Flows](/docs/kyb-know-your-business/kyb-flows.md) for request and response examples.

### Error Responses

#### 400 Bad Request

```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "flow must be a valid flow ID"
  ]
}
```

#### 401 Unauthorized

```json
{
  "statusCode": 401,
  "message": "Invalid API key"
}
```

#### 404 Not Found

```json
{
  "statusCode": 404,
  "message": "KYB flow not found"
}
```

### Next Steps

After creating a KYB case:

1. **Share the Verification Link** with your business customer via email or your application
2. **Set Up Webhooks** to receive real-time updates when the case status changes
3. **Monitor Case Progress** using `GET /kyb/case/{id}` endpoint
4. **Retrieve Results** once the case status changes to COMPLETED or REJECTED

### Related Documentation

* [KYB Overview](/docs/kyb-know-your-business/kyb-overview.md) - Understand the KYB verification flow
* [KYB Flows](/docs/kyb-know-your-business/kyb-flows.md) - Discover available KYB flow IDs
* [KYB Case Management](/docs/kyb-know-your-business/kyb-case-management.md) - Update and manage cases
* [KYB Webhooks](/docs/kyb-know-your-business/kyb-webhooks.md) - Receive real-time status updates

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.voveid.com/docs/kyb-know-your-business/kyb-create-case.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.