Generate KYC Verification Session
Authentication
Generate KYC Verification Session
Generate a Veriff verification session URL for identity verification during registration
POST
Generate KYC Verification Session
Overview
Generate a time-limited verification session URL for identity verification (KYC) during the registration flow. This endpoint creates a Veriff session that users complete to verify their identity before proceeding with personal details and address information. When to use:- After phone verification is complete
- Before collecting personal details and address
- User has not yet received an access token
onboardingId for session validation instead of a bearer token.
This endpoint is part of the registration flow and should be called before personal details submission. It does not require authentication.
Authentication
Your client public key for API authentication
Set to
true to route requests to the US backend environment (if available for your client)No Bearer Token Required: This endpoint is unauthenticated. Do not include an
Authorization header.Request
Body
Onboarding ID from email verification stepExample:
100a99cf-f4d3-4fa1-9be9-2e9828b20ebbResponse
Time-limited Veriff session URL. Direct the user to this URL to complete identity verification. The URL typically expires after 7 days and can be used multiple times until verification is complete.
Code Examples
Response Example
Error Responses
Error Response Details
Error Response Details
400 Bad Request
The onboarding ID is invalid, expired, or malformed. You need to:- Verify the onboardingId is a valid UUID
- Ensure the onboarding session hasn’t expired (typically 30-60 minutes)
- Restart registration from Step 1 if expired
404 Not Found
The onboarding session with this ID doesn’t exist:- The ID may be incorrect
- The session may have already been completed
- Restart registration if the session is lost
498 Invalid Token
The x-client-key header is invalid:- Verify your client key is correct
- Ensure the key is active and not revoked
- Contact support if you believe this is an error
500 Internal Server Error
An unexpected error occurred:- The verification provider may be unavailable
- Retry the request after a brief delay
- Contact support if the issue persists
Implementation Guide
Web Application Flow
Mobile Application Flow (React Native)
Handling Verification Completion
After the user completes Veriff verification, they will be redirected back to your application. The verification status is updated on the backend, but you should poll the onboarding status to detect completion:Verification Process Details
Required Documents
Users will need to provide:Government-Issued ID
Government-Issued ID
One of the following:
- Passport
- Driver’s license
- National ID card
- Residence permit
- Must be valid (not expired)
- Clear, readable photo of the document
- All corners visible in the image
Selfie Verification
Selfie Verification
- Live selfie or video recording
- Used for biometric matching with ID photo
- Ensures the person presenting the ID is the actual holder
Proof of Address (May Be Required)
Proof of Address (May Be Required)
Document showing current residential address (dated within last 3 months):
- Utility bill (electricity, water, gas)
- Bank statement
- Government correspondence
- Rental agreement
Verification Timeline
Quick Review (5-15 minutes)
Automated checks: Document authenticity, facial recognition, data extraction
Manual Review (15-60 minutes)
If automated checks are inconclusive, manual review by compliance team
Verification States
The user’s verification state will be updated based on the verification outcome:- UNVERIFIED: Initial state before verification
- PENDING: Verification submitted and under review
- VERIFIED: Verification approved
- REJECTED: Verification rejected (user can retry)
Important Notes
Multiple Attempts: If a user closes the Veriff session without completing it, they can use the same URL to resume. No need to generate a new session unless it has expired.
Common Issues
Verification Rejected
If verification is rejected, common reasons include:Document Issues
Document Issues
- Expired documents
- Poor image quality (blurry, dark, cut-off)
- Documents not accepted in user’s region
- Mismatched document information
Identity Mismatch
Identity Mismatch
- Selfie doesn’t match ID photo
- Name on documents doesn’t match registration
- Age doesn’t meet minimum requirements (typically 18+)
Fraud Detection
Fraud Detection
- Document appears altered or fake
- User on sanctions or watchlist
- Previous account with same credentials
- Suspicious behavior patterns
Retry After Rejection
When a user is rejected, they can proceed with registration and retry verification later using the authenticated endpoint:- Complete registration to get access token
- Use
GET /v1/user/verification(authenticated) to generate a new session - Ensure documents meet all requirements
- Submit with corrected/additional documents
Registration Flow Context
This endpoint is Step 3 in the registration process:- Email verification → get
onboardingId - Phone verification → use
onboardingId - → KYC verification → use
onboardingId(this endpoint) ← You are here - Personal details → use
onboardingId - Physical address → use
onboardingId, may getaccessToken - Mailing address (US only) → use
onboardingId, getaccessToken
No Bearer Token: This endpoint is unauthenticated because the user doesn’t have an access token yet. The access token is only issued after the address step completes.
Comparison with Post-Registration Verification
There are two verification endpoints:| Endpoint | When to Use | Authentication | Purpose |
|---|---|---|---|
POST /v1/auth/register/verification | During registration | onboardingId (no bearer token) | Initial KYC for new users |
GET /v1/user/verification | After registration | Bearer token required | Re-verification or verification for existing users |
Related Endpoints
Get Onboarding Status
Check verification status during registration
Update Personal Details
Next step after verification
Post-Registration Verification
For verified users who need to re-verify
Registration Guide
Complete registration flow documentation
Best Practices
User Guidance
User Guidance
Before redirecting users to verification:
- Explain why verification is required (regulatory compliance, security)
- List required documents (government ID, selfie)
- Estimate processing time (5-30 minutes)
- Provide preparation tips (good lighting, clear images, remove glasses)
Error Handling
Error Handling
Implement robust error handling:
- Network failures during session generation
- User closing verification window prematurely
- Session expiry (allow regeneration)
- Verification rejection (provide clear next steps)
Status Monitoring
Status Monitoring
After verification:
- Poll onboarding status periodically (every 5 seconds)
- Show loading state while verification processes
- Display clear success/failure messages
- Provide next steps based on outcome
Security
Security
- Never store or log verification session URLs (they contain sensitive tokens)
- Implement CSRF protection on your redirect endpoints
- Validate the user’s onboarding session before generating verification URL
- Use HTTPS for all communications