Skip to main content

​
Overview

This guide explains how to collect full verification (selfie + identity document) along with an additional identity document (e.g., residence permit) using the iDenfy API + WEB redirect. Common Use Case: Non-resident verification requiring both primary ID document AND residence permit.

​
Two Available Methods

How it works:
  • Generate two sessions with the same clientId
  • User completes two separate verification sessions
  • Chain them together using redirect URLs for a smooth transition
  • Both documents are fully processed with automatic data extraction
  • Use the same clientId to link both webhook responses and compare the extracted identity fields (e.g. first name, last name, date of birth) to verify that both documents belong to the same person.
User Experience:
  1. Complete identity verification (selfie + ID)
  2. Automatically redirected to residence permit upload
  3. Two separate sessions, seamless flow

​
Method 2: Additional Steps

How it works:
  • Single with an additional document step configured
  • User completes everything in one session
  • Limitation: An Additional identity document is only stored (UPLOAD), no automatic data extraction or comparison
User Experience:
  1. Complete identity verification (selfie + ID)
  2. The system shows an additional step
  3. Upload additional identity document - can be specified in account settings by contacting technical support
  4. Everything in one session
Main Reason to Choose Method 1: Full automatic data extraction from both documents, making it easier to validate that both documents belong to the same person.

​
Method 1: Two Separate Sessions (Sequential Flow)

This is the recommended approach for a smooth user experience with full data extraction from both documents.

​
Step 1: Generate Both Sessions

Document Verification Session: POST https://ivs.idenfy.com/api/v2/ { “clientId”: “USER_12345”, “firstName”: “John”, “lastName”: “Smith”, “dateOfBirth”: “1990-05-15”, “tokenType”: “DOCUMENT”, “successUrl”: “https://yoursite.com/verification/complete”, “errorUrl”: “https://yoursite.com/verification/failed”, “unverifiedUrl”: “https://yoursite.com/verification/review”, “callbackUrl”: “https://yoursite.com/webhook/idenfy” } Response: { “authToken”: “TOKEN_XYZ789”, “scanRef”: “scan-ref-document”, “clientId”: “USER_12345” } Identity Verification Session: From Document Verification response take “authToken” value and provide for URLs(“successUrl“, “errorUrl“, “unverifiedUrl“) which will redirect user automatically to the second document verification redirect URLs example https://ivs.idenfy.com/api/v2/redirect?authToken=TOKEN\_XYZ789 POST https://ivs.idenfy.com/api/v2/token Authorization: Basic {API_KEY:API_SECRET in base64} { “clientId”: “USER_12345”, “firstName”: “John”, “lastName”: “Smith”, “dateOfBirth”: “1990-05-15”, “tokenType”: “IDENTIFICATION”, “successUrl”: “https://ivs.idenfy.com/api/v2/redirect?authToken=TOKEN\_XYZ789”, “errorUrl”: “https://ivs.idenfy.com/api/v2/redirect?authToken=TOKEN\_XYZ789”, “unverifiedUrl”: “https://ivs.idenfy.com/api/v2/redirect?authToken=TOKEN\_XYZ789”, “callbackUrl”: “https://yoursite.com/webhook/idenfy” } Response: { “authToken”: “TOKEN_ABC123”, “scanRef”: “scan-ref-identity”, “clientId”: “USER_12345” }

​
Step 2: Build Verification URLs

const identityUrl = `https://ivs.idenfy.com/api/v2/redirect?authToken=${identityToken.authToken}\`; // Send user to identity verification window.location.href = identityUrl;

​
Step 3: Handle Webhooks and Compare Data

You’ll receive two separate webhooks - one for each verification. Webhook Handler: javascript const verifications = {}; // Store by clientId app.post(‘/webhook/idenfy’, async (req, res) => { const payload = req.body; const clientId = payload.clientId; if (!verifications[clientId]) { verifications[clientId] = {}; } // Store based on scanRef or tokenType if (payload.tokenType === ‘IDENTIFICATION’) { verifications[clientId].identity = payload; } else { verifications[clientId].document = payload; } // Check if both completed if (verifications[clientId].identity && verifications[clientId].document) { const identity = verifications[clientId].identity.data; const document = verifications[clientId].document.data; // Compare to ensure same person const isMatch = identity.docFirstName === document.docFirstName && identity.docLastName === document.docLastName && identity.docDob === document.docDob; if (isMatch) { await updateUserStatus(clientId, ‘VERIFIED’); } else { await updateUserStatus(clientId, ‘REQUIRES_REVIEW’); } } res.status(200).send(‘OK’); }); Fields to Compare suggestion:
  • First Name
  • Last Name
  • Date of Birth

​
User Journey

1. User clicks verification link ↓ 2. Opens: https://ivs.idenfy.com/api/v2/redirect?authToken=IDENTITY\_TOKEN ↓ 3. Completes selfie + ID document ↓ 4. iDenfy redirects to: https://ivs.idenfy.com/api/v2/redirect?authToken=DOCUMENT\_ ↓ 5. User capture additional identity document ↓ 6. iDenfy redirects to: https://yoursite.com/verification/complete ↓ 7. Two webhooks received - compare data to validate same person by same clientID

​
Method 2: Additional Steps (Alternative)

Use this when you don’t need data extraction from the additional document.

​
Setup

Contact iDenfy support to configure additional step in your environment:
  • Step name: “RESIDENCE_PERMIT” or similar by your case

​
Generate Session

POST https://ivs.idenfy.com/api/v2/token { “clientId”: “USER_12345”, “firstName”: “John”, “lastName”: “Smith”, “tokenType”: “IDENTIFICATION” // Additional step included automatically from environment config }

​
Response

{ “authToken”: “TOKEN_ABC123”, “scanRef”: “scan-ref”, “additionalSteps”: { “ALL”: { “ALL”: { “RESIDENCE_PERMIT”: { “type”: “UPLOAD”, “texts”: { “en”: { “name”: “Please upload your residence permit” } } } } } } }

​
Provide URL to User

const verificationUrl = `https://ivs.idenfy.com/api/v2/redirect?authToken=${response.authToken}\`; window.location.href = verificationUrl;

​
Webhook Result

{ “final”: true, “status”: { “overall”: “APPROVED” }, “data”: { “docFirstName”: “JOHN”, “docLastName”: “SMITH”, “docDob”: “1990-05-15” // No extraction from additional document }, “fileUrls”: { “FACE”: “https://…”, “FRONT”: “https://…”, “RESIDENCE_PERMIT”: “https://…” // Document stored here }, “additionalSteps”: { “RESIDENCE_PERMIT”: “UPLOAD” } } Note: Additional document is only stored - no automatic data extraction. You need to manually review or process the document.

​
API Reference