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

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

{
  "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/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 for request and response examples.

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

• KYB Case Details - Retrieve the public KYB case details contract

• KYB Flows - Discover available KYB flow IDs

• KYB Webhooks - Receive real-time status updates