Verifying ID document - API only (IDC) (v1)

Stable / GA

This is the current stable version of this step type.
A successor version of this step is in preview / alpha: Verifying ID document - API only (IDC) (v2)

Automated verification using pre‑captured document and face images

Verifies identity using static evidence collected by your own front end and submitted to IDnow via API.

In Headless mode, your application is responsible for collecting and providing identity evidence, such as images of the ID document. IDnow then performs verification on these static inputs using AI-based analysis and data extraction modules. Unlike Capture mode, the Headless flow does not involve any user interaction within the IDnow front end; all evidence is provided directly by the customer’s system.

Because verification relies solely on static images, certain checks that require dynamic interaction or live capture cannot be performed. As a result, this IDV method provides a more limited level of accuracy and is not suitable for regulated use cases such as KYC or AML processes.

Instead, this step is best suited for unregulated scenarios, such as document data extraction, image quality assessment, or pre-validation steps where full dynamic verification is not required.

---

Key features

• Customer-managed evidence collection: The customer application captures and submits document images via API.
• Static evidence processing: Verification is performed using only static images, without live interaction or dynamic capture.
• AI-based analysis: Automated checks assess document authenticity and extract identity data.
• Lightweight integration: Ideal for API-based use cases that require automated data extraction or streamlined verification flows.

Step compatibility

This step, Verifying IBAN - API only (v1), and Verifying proof of address - API only (v1) each require a different document type and cannot be combined in the same flow.

---

Configuration

Option	Type	Required	Description
config	object	Yes	Environment-specific configuration.
config.live.realm	string	Yes	The realm identifier for the document verification service. Provided by IDnow during onboarding. (live)
config.staging.realm	string	Yes	The realm identifier for the document verification service. Provided by IDnow during onboarding. (staging)

Example configuration

{
  "config": {
    "live": { "realm": "your-live-realm" },
    "staging": { "realm": "your-staging-realm" }
  }
}

---

Input data blocks

Data block	Required	Description
DocumentImages	Yes	Contains vault references ({ "$ref": "vault", "$id": "<uuid>" }) to the identity document images. This data block is always required. File size limit: 4MB.

Specific requirements for DocumentImages

The DocumentImages data block supplied to this step must carry an ID-category document type (passport, driving licence, national ID card, etc.)

---

Routes

Route	Description
verified	Document was successfully processed and identity data was extracted.
not_verified	Document verification failed; no identity data could be extracted.
fraud_detected	Document was identified as fraudulent; no identity data was extracted.

---

Output data blocks

Route	Data blocks produced
verified	BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, DocumentVerification
not_verified	DocumentVerification
fraud_detected	DocumentVerification

Example payloads

BasicIdentity — verified

{
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": "1985-03-22",
  "birthPlace": "Paris"
}

ExtendedIdentity — verified

{
  "portrait": {
    "$ref": "vault",
    "$id": "020ff369-43d8-4b8a-94e7-6814c0bdc35a"
  },
  "nationality": "FRA",
  "personalAdministrativeNumber": null,
  "familyNameBirth": "Dupont",
  "givenNameBirth": "Jean",
  "sex": 1,
  "emailAddress": null,
  "mobilePhoneNumber": null,
  "residentAddress": "24 RUE DANTON 35700 RENNES FRANCE",
  "residentStreet": "RUE DANTON",
  "residentHouseNumber": "24",
  "residentHouseName": null,
  "residentCountry": "FR",
  "residentState": "Bretagne",
  "residentCity": "RENNES",
  "residentPostalCode": "35700"
}

DocumentData — verified

{
  "documentType": "ID",
  "documentNumber": "D123456789",
  "expiryDate": "2030-06-15",
  "issuanceDate": "2020-06-15",
  "issuingCountry": "FR",
  "issuingAuthority": "Préfecture de Paris"
}

DocumentVerification — verified (deprecated — use Verification in DOC_ID_HEADLESS:v2)

DocumentVerification — verified

{
  "verdict": {
    "status": "VERIFIED",
    "reason": null
  },
  "issues": [],
  "report": {
    "$ref": "vault",
    "$id": "7f3c1a2b-9e45-4d78-b012-3f6a8c9d2e14"
  },
  "evidences": [
    {
      "type": "documentFrontOriginalImage",
      "ref": {
        "$ref": "vault",
        "$id": "4d29f1a3-8c72-4e56-b901-2f5d7e8c3a19"
      }
    }
  ]
}

DocumentVerification — not_verified (deprecated — use Verification in DOC_ID_HEADLESS:v2)

DocumentVerification — not_verified

{
  "verdict": {
    "status": "REJECTED",
    "reason": "DOCUMENT_UNREADABLE"
  },
  "issues": [
    {
      "code": "DOCUMENT_UNREADABLE",
      "severity": "error",
      "message": "The document image quality is too low to perform verification."
    }
  ],
  "report": null,
  "evidences": []
}

DocumentVerification — fraud_detected (deprecated — use Verification in DOC_ID_HEADLESS:v2)

DocumentVerification — fraud_detected

{
  "verdict": {
    "status": "FRAUD_DETECTED",
    "reason": "DOCUMENT_TAMPERED"
  },
  "issues": [
    {
      "code": "DOCUMENT_TAMPERED",
      "severity": "error",
      "message": "Signs of document tampering were detected."
    }
  ],
  "report": null,
  "evidences": []
}

---