KYB integration guide
Integrate KYB from flow selection through applicant submission and review.
This guide connects the KYB API, hosted applicant journey, webhooks, dashboard review, and final case retrieval.
1. Select a flow
Use GET /kyb/flows to list available country flows. There is no default KYB flow. Pass flow when you want to start with a specific country configuration. Omit flow to let the applicant choose the business country in the hosted journey.
Review its business-information fields, ownership and control questions, required documents, UBO KYC flow, registry search, and optional website analysis.
2. Create the case
Call POST /kyb/case from your backend with a stable refId:
{
"refId": "business-7f3d",
"flow": "66f000000000000000000010"
}Persist the refId and returned case ID. Do not log the case token.
3. Deliver the hosted journey
Build the Sandbox URL:
const url = new URL('/kyb', 'https://web.voveid.net');
url.searchParams.set('authToken', token);
url.searchParams.set('publicKey', 'public_sandbox_replace_me');
url.searchParams.set('environment', 'Sandbox');Deliver it only to the intended applicant. The token expires after 24 hours. If it expires, create a new case or regenerate the token through your approved integration process.
4. Applicant completion
The applicant completes the steps configured by the selected flow. These can include:
Business and registration information.
Addresses and operating jurisdictions.
Ownership, control, and related businesses.
Supporting documents.
Registry selection.
UBO invitations and individual KYC.
Website analysis.
The applicant reviews the entered information and submits the case for review.
5. Synchronize status
Verify and deduplicate KYB webhooks. Store every transition, but retrieve the current case before applying a final decision.
NOT_STARTED
Link issued; journey not started
Wait or reissue after token expiry
IN_PROGRESS
Applicant is completing steps
Keep onboarding pending
IN_REVIEW
Applicant submitted the case
Review it in KYB Cases in the dashboard
COMPLETED
Review completed
Retrieve details and apply the approved policy
REJECTED
Case rejected
Retrieve reason/details and apply the approved recovery path
6. Review the case
Review every submitted case from KYB Cases in the VOVE ID dashboard. Compare submitted values with registry/provider evidence and documents. Review UBO results, AML summaries, website analysis, flags, notes, and history. Record the evidence and reason for every request, approval, rejection, or reopen action.
Automated extraction, scores, and external-data matches are supporting evidence, not independent approval authority.
7. Retrieve the final resource
See Get KYB case details for the full response model.
Recovery
Token expired
Create a new case or regenerate the token through your approved integration process
Wrong flow selected
Stop applicant work and confirm the replacement path before recreating
UBO cannot complete KYC
Preserve references and use the approved support or manual path
Registry match is ambiguous
Request evidence or escalate; do not select on name alone
Webhook is delayed
Retrieve case details and keep onboarding pending
Evidence conflicts
Escalate under your review policy and record the reason
Last updated