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
This endpoint is unauthenticated and uses the 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.
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.
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:
Copy
async function pollVerificationStatus(onboardingId: string): Promise<void> { const maxAttempts = 60; // 5 minutes with 5-second intervals let attempts = 0; return new Promise((resolve, reject) => { const poll = setInterval(async () => { try { const response = await fetch( `https://dev.api.baanx.com/v1/auth/register?onboardingId=${onboardingId}`, { headers: { 'x-client-key': process.env.NEXT_PUBLIC_CLIENT_KEY! } } ); const user = await response.json(); // Check if verification state has changed if (user.verificationState === 'VERIFIED' || user.verificationState === 'PENDING') { clearInterval(poll); resolve(); } else if (user.verificationState === 'REJECTED') { clearInterval(poll); reject(new Error('Verification was rejected')); } attempts++; if (attempts >= maxAttempts) { clearInterval(poll); reject(new Error('Verification polling timeout')); } } catch (error) { clearInterval(poll); reject(error); } }, 5000); // Poll every 5 seconds });}// Usagetry { await pollVerificationStatus(onboardingId); showSuccessMessage('Verification complete! Proceeding to personal details.'); // Navigate to personal details step} catch (error) { showErrorMessage('Verification incomplete. Please try again.');}
Session Expiry: The verification session URL typically expires after 7 days. However, users can use the same URL multiple times during this period if they need to restart the process.
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.
User Experience: For the best user experience:
Display a clear message explaining why verification is needed
Show what documents will be required (government ID)
Inform users about the typical processing time (5-30 minutes)
Provide a way to check verification status after completion
Consider opening Veriff in a modal or in-app browser rather than redirecting
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 get accessToken
Mailing address (US only) → use onboardingId, get accessToken
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.