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.

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

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

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

Response

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

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

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:

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.

4. Review the submitted case in KYB Cases in the VOVE ID dashboard.

5. Retrieve case details before applying your final decision.