Skip to main content

​
Overview

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

​
Choosing a Method

Method 1: Two separate sessionsMethod 2: Additional steps
SessionsTwo sessions with the same clientIdSingle session
Data extractionFull automatic extraction from both documentsAdditional document is stored only — no extraction
Data comparisonCompare extracted fields (name, DOB) to verify same personManual review required
SetupNo extra configuration neededRequires iDenfy support to configure the additional step
Recommendation: Use Method 1 if you need automatic data extraction and comparison between documents.

​
Method 1: Two Separate Sessions

Generate two sessions with the same clientId, chain them using redirect URLs, and compare the webhook results.

​
Step 1: Generate Both Sessions

Create the identity verification session first. Set its redirect URLs to point to the second session’s redirect URL. 
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=DOCUMENT_TOKEN",
  "errorUrl": "https://ivs.idenfy.com/api/v2/redirect?authToken=DOCUMENT_TOKEN",
  "unverifiedUrl": "https://ivs.idenfy.com/api/v2/redirect?authToken=DOCUMENT_TOKEN",
  "callbackUrl": "https://yoursite.com/webhook/idenfy"
}
Then create the document verification session: 
{
  "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"
}
Use the authToken from the document session response as DOCUMENT_TOKEN in the identity session’s redirect URLs. This chains the two sessions so the user is automatically redirected after completing the first verification.

​
Step 2: Send the User to Verification

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

​
Step 3: Handle Webhooks and Compare Data

You will receive two separate webhooks — one for each session. Use the clientId to link them and compare extracted data. 
const verifications = {};

app.post('/webhook/idenfy', async (req, res) => {
  const payload = req.body;
  const clientId = payload.clientId;

  if (!verifications[clientId]) {
    verifications[clientId] = {};
  }

  if (payload.tokenType === 'IDENTIFICATION') {
    verifications[clientId].identity = payload;
  } else {
    verifications[clientId].document = payload;
  }

  // Check if both sessions are complete
  if (verifications[clientId].identity && verifications[clientId].document) {
    const identity = verifications[clientId].identity.data;
    const document = verifications[clientId].document.data;

    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');
});
Suggested fields to compare: first name, last name, date of birth.

​
User Journey

  1. User clicks verification link
  2. Opens identity verification (selfie + ID)
  3. Completes identity verification
  4. Automatically redirected to document verification (residence permit)
  5. Uploads additional document
  6. Redirected to your success URL
  7. Two webhooks received — compare data to validate the same person

​
Method 2: Additional Steps

Use this when you do not need data extraction from the additional document.

​
Setup

Contact iDenfy support to configure an additional step in your environment (e.g., RESIDENCE_PERMIT).

​
Generate Session

POST https://ivs.idenfy.com/api/v2/token
Authorization: Basic {API_KEY:API_SECRET in base64}

{
  "clientId": "USER_12345",
  "firstName": "John",
  "lastName": "Smith",
  "tokenType": "IDENTIFICATION"
}
The additional step is included automatically from your environment configuration.

​
Webhook Result

{
  "final": true,
  "status": {
    "overall": "APPROVED"
  },
  "data": {
    "docFirstName": "JOHN",
    "docLastName": "SMITH",
    "docDob": "1990-05-15"
  },
  "fileUrls": {
    "FACE": "https://...",
    "FRONT": "https://...",
    "RESIDENCE_PERMIT": "https://..."
  },
  "additionalSteps": {
    "RESIDENCE_PERMIT": "UPLOAD"
  }
}
The additional document is stored only — no automatic data extraction. You will need to manually review or process the document image from fileUrls.