Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt

Use this file to discover all available pages before exploring further.

Requirements:
  • API key pair
  • Direct Processing feature enabled on your contract (contact iDenfy to activate)
Limitations:
  • Does not support 3D liveness detection or short photo sequences. Use a different integration type if these are required.
  • Maximum request size: 20 MB (total across all images).
  • Cannot be used to update an existing verification. Use the Request Update feature or re-verify using the same clientId via session creation.
  • Digital ID types are not supported and will be rejected.

​
How It Works

Direct processing lets you submit document images in a single POST request. The API responds immediately — the actual OCR, face matching, fraud checks, and AML screening all run asynchronously after the response. Results are delivered via webhook.

​
Endpoint

POST https://ivs.idenfy.com/api/v2/process
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json

​
Request Parameters

​
Required

The verification session token generated beforehand via session creation.
  • Must be valid, unused, and belong to the authorized partner.
  • Deactivated immediately after the request — cannot be reused.
  • Must not have questionnaire answers (kyc_answers) attached.
  • NFC must not be required for the session.
ISO 3166-1 alpha-2 country code (e.g. LT, US, DE). Converted to uppercase automatically. Must be a valid recognized country code.
A dictionary of Base64-encoded images, keyed by side:
KeyDescriptionRequired
FRONTDocument frontAlways
BACKDocument backWhen the document type has a back side
FACESelfieRequired for identification sessions; optional for document-only
UTILITY_BILLUtility bill image or PDFWhen configured as a required step on the token
SECOND_UTILITY_BILLSecond utility billWhen configured
Supported formats: PNG, JPG, JPEG, PDF. Encrypted or password-protected PDFs are rejected.

​
Optional

Specifies the document being submitted. Valid values: ID_CARD, PASSPORT, DRIVER_LICENSE, RESIDENCE_PERMIT.If omitted, the system automatically detects the document type from the FRONT image. If auto-detection fails, the request is rejected with an error.
When documentType is provided, BACK becomes required if that document type has a back side.
Set to true to skip photo quality checks (blur, glare, document detection). Useful when a valid photo fails standard detection.Does not skip data extraction or fraud checks — only the photo validation step.

​
Verification Types

The session tokenType set during session creation determines what images are expected:
  • IDENTIFICATION (default): Requires a FACE image. Face matching runs against the document photo.
  • DOCUMENT: Document-only. Face step is removed automatically — no FACE image or liveness check required. Result is marked FACE_NOT_CHECKED.

​
Additional Steps

Some verification flows require extra document checks beyond the main identity document — for example, a utility bill for address verification. These are configured as additional steps on the token at session creation, not in the /v2/process call itself. How it works:
  1. Token creation — the partner sets up the token with UTILITY_BILL as a required additional step, and optionally passes a reference address to compare against via additionalData: 
    {
  "additionalData": {
    "UTILITY_BILL": {
      "address": "123 Main St, City"
    }
  }
}
  2. Direct processing call — the partner includes the utility bill image inside the images object alongside the main document images. No extra fields are needed in the /v2/process request body.
  3. Processing — depending on the step configuration, the system will:
    ModeBehaviour
    UPLOADStores the image; no analysis
    EXTRACTExtracts the address from the bill; no comparison
    COMPAREExtracts the address and checks it against the reference address from additionalData

​
Conditions & Rules

ConditionRule
Partner accessPartner must have direct processing enabled in their contract — if not, the request is rejected
Token with questionnaireNot allowed. Token must have no kyc_answers attached
NFC required tokenNot allowed with direct processing
documentType omittedOnly FRONT is mandatory; document type is auto-detected from the image
documentType providedBACK becomes required if that document type has a back side
FACE imageRequired when the session type includes face matching
PDF submittedMust not be password-protected
Token reuseToken is deactivated after one direct processing call

​
Request Examples

With explicit document type: 
{
  "token": "3FA5TFPA2ZE3LMPGGS1EGOJNJE",
  "country": "LT",
  "documentType": "ID_CARD",
  "images": {
    "FRONT": "/9j/4AAQSkZJRgABAQAAAQABAAD/4...",
    "BACK": "/9j/4AAQSkZJRgABAQAAAQABAAD/4...",
    "FACE": "/9j/4AAQSkZJRgABAQAAAQABAAD/4..."
  }
}
With auto document type detection (documentType omitted): 
{
  "token": "3FA5TFPA2ZE3LMPGGS1EGOJNJE",
  "country": "LT",
  "images": {
    "FRONT": "/9j/4AAQSkZJRgABAQAAAQABAAD/4...",
    "FACE": "/9j/4AAQSkZJRgABAQAAAQABAAD/4..."
  }
}

​
Response

A successful request returns HTTP 200 with no response body. Processing continues asynchronously.

​
Error Response

Failed requests return a JSON body identifying the problem: 
{
  "message": "No image provided for step 'BACK'",
  "identifier": "MISSING_VALUE",
  "documentation": "",
  "severity": "NOT_SEVERE"
}
A 200 OK with an error message body may indicate the document was not detected in the photo. If this happens:
  • Add "skipAnalysis": true to the request, or
  • Use a clearer photo with a fully visible document.
See the full list of error messages.

​
What Happens After

Once the request is accepted, processing runs asynchronously:
  1. OCR extracts document fields — name, date of birth, expiry, document number, nationality, and more.
  2. Face matching runs if a FACE image was provided.
  3. Fraud checks and AML/sanctions screening run automatically.
  4. Results are delivered via webhook to your configured endpoint.
See Webhooks for payload details.