Government ID and Selfie Match

Overview

Government ID and Selfie Match verifies identity via government-issued ID document capture and biometric selfie matching. The document is authenticated (not just read) and the selfie is compared biometrically to the document photo with liveness detection.

Two variants are available under this step: Standard (one document + selfie) and Dual Document (two documents + selfie). Both share the same API integration and configuration options — the difference is that Dual Document runs two independent document capture sessions and requires both to pass.

Level of Assurance

Standard: High — document authentication + biometric face match. Dual Document: Very High — dual document authentication + biometric face match + cross-document consistency.

User Friction Level

Standard: Medium — one document capture + selfie. Dual Document: Medium-High — two document captures + selfie.

End User Requirements

Standard: One government-issued photo ID (passport, driver's license, or ID card), mobile device with camera, adequate lighting. Dual Document: Two government-issued photo IDs (e.g., passport + driver's license), mobile device with camera.

Speed

Standard: 1–2 minutes. Dual Document: 2–3 minutes.

Supported Countries

180+ countries; thousands of document types supported. Document type availability varies by country.

Use Cases & Fraud Prevention

• High-assurance KYC/onboarding — regulated industries, financial services, healthcare, government.
• Document step-up within Identity Verification and NIST IAL2 workflows — for users who cannot be corroborated via phone-based identity match.
• Dual Document: high-risk or high-compliance use cases where a single document is insufficient; makes document forgery significantly harder via cross-document consistency checks.
• Mitigates: document fraud, impersonation, deepfakes, synthetic identity.

How It Works

Standard

User selects their document type (passport, driver's license, or ID card). On desktop, an SMS link or QR code delivers the capture flow to their mobile device. On mobile, capture proceeds directly. The user photographs the front (and back if required) of their ID, then takes a selfie. Liveness detection runs on the selfie.

The platform checks:

• Document is classifiable and an allowable type
• Document is authentic (not a reproduction or forgery)
• Selfie matches the document headshot biometrically
• Full name on document matches claimed name
• Document is not expired
• Selfie passes liveness detection

All checks must pass for approval. A failed documentClassified check cascades — all downstream assertions fail if the document cannot be read.

Dual Document

The flow runs identically to Standard for the first document. After the first document passes, the user is prompted to capture a second document. The second document is independently authenticated and cross-referenced against the selfie and claimed name. Both document assertion sets must pass for approval. Either document failing causes the step to fail.

Configuration Options

Template Variations

• Standard Government ID and Selfie Match — one document + selfie (default)
• Dual Document Government ID and Selfie Match — two documents + selfie
• Document types accepted — configurable: all types, passport only, or a specific subset
• Desktop delivery method — SMS link (default) or QR code

Optional Add-ons

• PII Validation as a pre-check — for US/UK/CA users, adding MobileMatch before Government ID and Selfie Match provides a phone-based assurance layer before document capture is required
• Verification Selector — dynamically routes users to Government ID and Selfie Match or Dynamic KBA based on policy, rather than always requiring document capture
• Email Risk at the preceding Session Risk step — early filter before the user reaches document capture
• DMV Validation The data extracted from the license can be checked against DMV for accuracy.

Integration: Gateway (OIDC)

Standard OIDC flow. See Gateway (OIDC) Integration. The document capture session (including desktop-to-mobile handoff) is handled by the hosted UI — your application only sees the final authorization code.

Step-by-step Setup

• Navigate to the Workflow page in the Admin Console and deploy a workflow that includes Government ID and Selfie Match.
• Configure asyncUIRedirect — required for the document capture path to return control to your application after capture is complete.
• QR code delivery is available as an alternative to SMS for desktop-to-mobile handoff — contact your ID Dataweb team to enable.

Integration: ID Dataweb API

Government ID and Selfie Match uses an async capture flow. Your app initiates a capture session, the user completes document and selfie capture on their mobile device, and your app retrieves the result. Two decisions shape your integration: how the capture link reaches the user, and how your app knows when capture is done.

API Prerequisites

When to use what

Delivery method — how the capture link reaches the user:

Result retrieval — how your app knows capture is complete:

1. Deliver the capture link

Call one of the three endpoints to initiate a capture session. All three return an asi (async session ID) — save this value, you'll need it in step 3.

sequenceDiagram
    participant App as Your Application
    participant IDW as ID Dataweb API
    participant User as End User

    Note over App,IDW: forwardApiKey from preceding step = Government ID and Selfie Match step key

    App->>IDW: POST /async-ui/send-link<br/>POST /async-ui/get-link<br/>POST /async-ui/qr-code
    IDW-->>App: asi + link or QR image
    IDW->>User: SMS delivered (send-link only)
    Note over App,User: get-link: you deliver the URL<br/>qr-code: you render the image on screen
    User->>IDW: Opens link and begins capture on mobile device

const response = await fetch('https://api.preprod.iddataweb.com/v1/async-ui/send-link', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apikey: BIOGOVID_STEP_KEY,
    credential: '[email protected]',
    appID: 'Your Application Name',
    country: 'US',
    userAttributes: [
      { attributeType: 'InternationalTelephone', values: { dialCode: '1', telephone: '1234567890' } },
      { attributeType: 'FullName', values: { fname: 'First', mname: '', lname: 'Last' } }
    ]
  })
});

{
  "services": [{ "apTransactionId": "string", "name": "Government ID and Selfie Match Verification", "status": "delivered", "apSessionId": "string" }],
  "asi": "string"
}

2. Get the result back

Once the user completes capture, your app needs to know it's done before calling /slverify.

Option A — Redirect

Use when: Your backend is publicly accessible on the internet.

After capture completes, the platform redirects the user's browser to your asyncUIRedirect URL with the asi appended as a query parameter. Your backend receives a real-time inbound GET request the moment capture is done — no polling required, no delay.

Configure asyncUIRedirect in the Admin Console before going live. Your backend must expose a publicly reachable GET endpoint at that URL.

sequenceDiagram
    participant User as End User
    participant IDW as ID Dataweb API
    participant App as Your Application

    User->>IDW: Completes document capture + selfie on mobile
    IDW->>User: Redirects browser to asyncUIRedirect?asi=...
    User->>App: GET /your-redirect-endpoint?asi=ABC123
    Note over App: Read asi from query param → proceed to /slverify

// Your redirect endpoint — receives the user after capture completes
app.get('/your-redirect-endpoint', async (req, res) => {
  const asi = req.query.asi; // read asi from query param
  // proceed to /slverify with this asi — see step 3
});

Option B — Polling

Use when: Your backend is behind a firewall, on an internal network, or you are building a mobile app or local dev environment that cannot receive inbound HTTP.

Your app polls the results endpoint every 3–5 seconds until capture is complete. Less efficient than redirect but works in any environment.

sequenceDiagram
    participant App as Your Application
    participant IDW as ID Dataweb API
    participant User as End User

    User->>IDW: Completes document capture + selfie on mobile
    loop Poll every 3–5 seconds
        App->>IDW: GET /doccapture/results?asi=...
        IDW-->>App: status: pending | success
    end
    Note over App: status = success → proceed to /slverify

// Poll until capture is complete
async function waitForCapture(asi, accessToken) {
  while (true) {
    const res = await fetch(`https://api.preprod.iddataweb.com/v1/doccapture/results?asi=${asi}`, {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    });
    const data = await res.json();
    if (data.status === 'success') return;
    await new Promise(r => setTimeout(r, 4000)); // wait 3–5 seconds between polls
  }
}

3. Call /slverify

The same regardless of which delivery method or retrieval path you used. Pass the asi from step 1 to get the final policyDecision.

const response = await fetch('https://api.preprod.iddataweb.com/v1/slverify', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apikey: BIOGOVID_STEP_KEY,
    credential: userCredential, // same credential value used throughout the session
    asi: asi,
    country: 'US',
    userAttributes: [
      { attributeType: 'FullName', values: { fname: 'First', mname: '', lname: 'Last' } }
    ]
  })
});

{
  "errorCode": "string",
  "errorDescription": "string",
  "transaction_id": "string",
  "acquiredAttributes": [{ "provider": "Incode", "serviceOffering": "Incode Government ID and Selfie Match Verification", "attributeType": "string", "dateCreated": "MM/DD/YYYY HH:mm:ss", "values": {} }],
  "policyDecision": "approve | deny",
  "forwardApiKey": "string",
  "mbun": "string"
}

credential should be the same value used throughout the session (e.g. username or email). mbun (Master Business Unit Number) is a stable cross-session identifier assigned on approval.

The Dual Document flow uses the same three steps — the dual capture is handled within the hosted capture session and requires no additional API calls.

Step-by-step Setup

• Use the forwardApiKey from the preceding step as your BIOGOVID_STEP_KEY.
• Choose your delivery method (Send Link / Get Link / QR Code) and call the corresponding endpoint. Save the asi from the response.
• Choose your retrieval method: configure asyncUIRedirect and implement the redirect endpoint, or implement a polling loop against /doccapture/results.
• Once capture is confirmed complete (via redirect callback or poll success), call POST /slverify with the asi.
• On policyDecision = approve, use forwardApiKey for the next step if the workflow continues.

Policy Components & Decisioning

Key assertions evaluated:

All assertions must pass for policyDecision = approve. For Dual Document, the full assertion set runs independently for each document — both must pass.

Error Handling & Troubleshooting

• test.documentClassified = Fail: Document not recognized — try a different document type or retake with better lighting. This failure cascades to all downstream assertions.
• test.selfieLiveness = Fail: Selfie appears to be a photo-of-photo — the user must take a live selfie.
• test.facialPhotosMatch = Fail: Selfie does not match document — user must present their own ID.
• Image quality failures: The most common cause of false denials. A retry under better lighting usually resolves.
• test.documentAuthenticated = Fail: Document failed authentication checks — do not retry with the same document.

Testing in Preproduction

Testing Options

• Gateway (Try Now): Admin Console. Document type selection determines the outcome (Passport = approve, Driver's License = deny, ID Card = real verification).
• API: Government ID and Selfie Match Postman Collection with preproduction endpoint and test tenant.

Test Credentials and Values

For Dual Document: select Passport for both captures to get approve. Select Driver's License for either to get deny.

Step-by-step How to Test

• Approve: Enter Andrew Roshell data → select Passport → submit any photo → expect approve.
• Deny: Same → select Driver's License → expect deny.
• Real capture (ID Card): Use an actual government ID and a live selfie.
• Dual Document — approve: Select Passport for both document capture sessions.
• Dual Document — deny: Select Driver's License for either session.

Interpreting Results

policyDecision = approve requires all assertions to pass. Key assertions to review on denial: documentClassified, selfieLiveness, facialPhotosMatch, documentAuthenticated. For Dual Document, assertion keys are prefixed or grouped per document — check both sets independently.

Related Resources

→ Identity Verification | → NIST IAL2 | → PII Validation | → Dynamic KBA | → Document + Selfie Match Checker | → Gateway (OIDC) Integration