Verifications

What is a Verification?

A Verification is the result of running checks against an identity document. When you create a verification, Beltic processes the associated document, performs a series of authenticity and data-quality checks, and returns a detailed result. Verifications are the core of the Identity API’s value — they tell you whether a document is genuine, whether the data can be trusted, and whether any issues were detected.

Verification Types

Type	Resource Type	Description
IDV	`verification/idv`	Verifies government-issued identity documents (passports, driver’s licenses, etc.)
Address	`verification/address`	Verifies proof of address documents

How Verification Works

When you create a verification, the following happens synchronously:

Document processing — The document images are analyzed using advanced document recognition
Data extraction — Personal information is extracted from the document (name, DOB, document number, etc.)
Check execution — Multiple verification checks are run against the document
Status determination — An overall status is computed from individual check results
Response — The complete verification result is returned

Verification creation is a synchronous operation. The response includes the full result — no polling required.

Creating a Verification

With a Session and Document

The most common pattern — verify a document within a session:

curl -X POST https://api.beltic.com/v1/identity/verifications \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "verification/idv",
      "relationships": {
        "document": {
          "data": { "type": "document/idv", "id": "doc_01HQ..." }
        },
        "session": {
          "data": { "type": "session", "id": "sess_01HQ..." }
        }
      },
      "meta": {
        "auto_update_session": true
      }
    }
  }'

Standalone (Without a Session)

You can also run a verification without a session — useful for API-only integrations:

curl -X POST https://api.beltic.com/v1/identity/verifications \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "verification/idv",
      "relationships": {
        "document": {
          "data": { "type": "document/idv", "id": "doc_01HQ..." }
        }
      }
    }
  }'

Verification Response

A verification response contains the status, extracted data, and check results:

{
  "data": {
    "type": "verification/idv",
    "id": "ver_01HQ...",
    "attributes": {
      "status": "passed",
      "capture_method": "api",
      "document_type": "passport",
      "classification_type": "identity",
      "name": {
        "first": "Jane",
        "middle": null,
        "last": "Doe"
      },
      "birth_date": "1990-05-15",
      "sex": "female",
      "document_number": "AB1234567",
      "issue_date": "2020-03-01",
      "expiry_date": "2030-03-01",
      "issuing_authority": "Department of State",
      "nationality": "US",
      "issuing_country": "US",
      "address": null,
      "checks": [
        {
          "name": "status_optical",
          "status": "passed",
          "requirement": "required",
          "reasons": [],
          "metadata": {}
        },
        {
          "name": "optical_expiry",
          "status": "passed",
          "requirement": "required",
          "reasons": [],
          "metadata": {}
        },
        {
          "name": "optical_mrz",
          "status": "passed",
          "requirement": "required",
          "reasons": [],
          "metadata": {}
        }
      ],
      "files": [],
      "front_side": { "id": "file_01...", "filename": "front.jpg" },
      "back_side": null,
      "portrait": { "id": "file_02...", "filename": "portrait.jpg" },
      "signature": null,
      "created_at": "2025-01-15T10:35:00Z",
      "submitted_at": "2025-01-15T10:35:00Z",
      "completed_at": "2025-01-15T10:35:02Z"
    },
    "relationships": {
      "session": {
        "data": { "type": "session", "id": "sess_01HQ..." }
      }
    }
  }
}

Verification Statuses

Status	Description
`initiated`	Verification has been created and processing has started
`passed`	All required checks passed
`failed`	One or more required checks failed
`requires_retry`	The verification could not be completed — typically due to image quality issues. The applicant should retry with better images.
`canceled`	The verification was canceled

Understanding Checks

Each verification includes an array of checks — individual tests performed against the document. Every check has:

Field	Description
`name`	Identifier of the check (e.g., `optical_mrz`, `status_optical`)
`status`	Result: `passed`, `failed`, or `not_applicable`
`requirement`	How the check affects the overall result: `required`, `not_required`, or `requires_retry`
`reasons`	Array of reason strings if the check failed
`metadata`	Additional details about the check

Check Categories

Status Checks

High-level status indicators from the document processing engine:

status_optical — Overall optical analysis result
status_portrait — Portrait/photo analysis result
status_rfid — RFID chip reading result (if applicable)

Optical Checks

Detailed analysis of the document’s visual elements:

optical_doc_type — Document type recognition
optical_expiry — Document expiration check
optical_image_qa — Image quality assessment
optical_mrz — Machine Readable Zone validation
optical_security — Security feature analysis
optical_text — Text consistency and validity

Authenticity Checks

Advanced fraud detection checks:

authenticity_uv_luminescence — UV luminescence patterns
authenticity_ir_b900 — Infrared B900 analysis
authenticity_image_pattern — Image pattern analysis
And more — the exact checks vary by document type and capture method

Image Quality Checks

Ensure the document images meet minimum quality standards:

image_quality_glare — Glare detection
image_quality_focus — Focus/sharpness assessment
image_quality_resolution — Resolution adequacy
And others for colorness, perspective, bounds, etc.

How Status is Determined

The overall verification status is computed from the individual checks:

If any check with requirement: "required" has status: "failed" → verification is failed
If any check has requirement: "requires_retry" → verification is requires_retry
If all required checks pass → verification is passed

Auto-Update Session

When you include "auto_update_session": true in the verification meta, the session is automatically updated with the extracted data from the document:

Person name (first, middle, last)
Date of birth
Sex
Address (if present on the document)

This saves you from manually copying extracted data to the session after each verification.

Listing Verifications

Retrieve verifications with optional filters:

# All verifications for a session
curl -X GET "https://api.beltic.com/v1/identity/verifications?filter[session_id]=sess_01HQ..." \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter by status
curl -X GET "https://api.beltic.com/v1/identity/verifications?filter[status]=passed" \
  -H "X-Api-Key: YOUR_API_KEY"

# Filter by type
curl -X GET "https://api.beltic.com/v1/identity/verifications?filter[type]=verification/idv" \
  -H "X-Api-Key: YOUR_API_KEY"

Next Steps

For a complete end-to-end example of running a document verification through the API, see Running a Document Verification.

Overview

Workflow API

Credentials API

Document API

Identity API (Legacy)

What is a Verification?

Verification Types

How Verification Works

Creating a Verification

With a Session and Document

Standalone (Without a Session)

Verification Response

Verification Statuses

Understanding Checks

Check Categories

How Status is Determined

Auto-Update Session

Listing Verifications

Next Steps

​What is a Verification?

​Verification Types

​How Verification Works

​Creating a Verification

​With a Session and Document

​Standalone (Without a Session)

​Verification Response

​Verification Statuses

​Understanding Checks

​Check Categories

​How Status is Determined

​Auto-Update Session

​Listing Verifications

​Next Steps

What is a Verification?

Verification Types

How Verification Works

Creating a Verification

With a Session and Document

Standalone (Without a Session)

Verification Response

Verification Statuses

Understanding Checks

Check Categories

How Status is Determined

Auto-Update Session

Listing Verifications

Next Steps