> 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/kyb-know-your-business/kyb-create-case.md). # 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 webhooks and the `GET /kyb/case/{refId}/details` endpoint 4. **Retrieve Results** from the public case details response 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 Case Details](/docs/kyb-know-your-business/kyb-case-management.md) - Retrieve the public KYB case details contract * [KYB Flows](/docs/kyb-know-your-business/kyb-flows.md) - Discover available KYB flow IDs * [KYB Webhooks](/docs/kyb-know-your-business/kyb-webhooks.md) - Receive real-time status updates