Direct Processing

Submit identity document images via a single API call for asynchronous server-side KYC verification — no SDK or user-facing session required.

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

token — string

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.

country — string

ISO 3166-1 alpha-2 country code (e.g. LT, US, DE). Converted to uppercase automatically. Must be a valid recognized country code.

images — object

A dictionary of Base64-encoded images, keyed by side:

Key	Description	Required
FRONT	Document front	Always
BACK	Document back	When the document type has a back side
FACE	Selfie	Required for identification sessions; optional for document-only
UTILITY_BILL	Utility bill image or PDF	When configured as a required step on the token
SECOND_UTILITY_BILL	Second utility bill	When configured

Supported formats: PNG, JPG, JPEG, PDF. Encrypted or password-protected PDFs are rejected.

Optional

documentType — string

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.

skipAnalysis — boolean (default: false)

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:

   Mode	Behaviour
   UPLOAD	Stores the image; no analysis
   EXTRACT	Extracts the address from the bill; no comparison
   COMPARE	Extracts the address and checks it against the reference address from additionalData

---

Conditions and Rules

Condition	Rule
Partner access	Partner must have direct processing enabled in their contract — if not, the request is rejected
Token with questionnaire	Not allowed. Token must have no kyc_answers attached
NFC required token	Not allowed with direct processing
documentType omitted	Only FRONT is mandatory; document type is auto-detected from the image
documentType provided	BACK becomes required if that document type has a back side
FACE image	Required when the session type includes face matching
PDF submitted	Must not be password-protected
Token reuse	Token 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.