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

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

Request Body

{
  "businessName": "Acme Corporation",
  "flow": "64a1b2c3d4e5f6g7h8i9j0k1",
  "refId": "unique-business-ref-12345",
  "formData": {
    "registrationNumber": "12345678",
    "country": "GB",
    "city": "London",
    "address": "123 Business Street"
  }
}

Parameters

Parameter	Type	Required	Description
businessName	string	No	The name of the business to be verified
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. If not provided, one will be generated. Used to retrieve case status later.

Response

Success Response (200 OK)

{
  "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:

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

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

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: If VOVE generates the refId, store it in your database for future reference

• Unique per Business: Each business entity should have a unique refId

Pre-filling Data

• Improve User Experience: Pre-fill as much business information as possible to reduce friction

• Required vs Optional: Check your KYB flow configuration to know which fields are required

• Data Accuracy: Ensure pre-filled data is accurate to avoid verification delays

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

• Default Flows: Use GET /kyb/flow/default/{country} to get the default flow for a country if you haven't created custom flows

Error Responses

400 Bad Request

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

401 Unauthorized

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

404 Not Found

{
  "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 - Understand the KYB verification flow

• KYB Case Management - Update and manage cases

• KYB Webhooks - Receive real-time status updates