Collecting Multiple Identity Documents

Collect multiple identity documents such as ID card plus residence permit in a single iDenfy verification using API and web redirect.

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 sessions	Method 2: Additional steps
Sessions	Two sessions with the same clientId	Single session
Data extraction	Full automatic extraction from both documents	Additional document is stored only — no extraction
Data comparison	Compare extracted fields (name, DOB) to verify same person	Manual review required
Setup	No extra configuration needed	Requires 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.

Related Pages

• Token generation
• Additional steps
• Webhooks