Skip to main content

​
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

TypeResource TypeDescription
IDVverification/idvVerifies government-issued identity documents (passports, driver’s licenses, etc.)
Addressverification/addressVerifies proof of address documents

​
How Verification Works

When you create a verification, the following happens synchronously:
  1. Document processing — The document images are analyzed using advanced document recognition
  2. Data extraction — Personal information is extracted from the document (name, DOB, document number, etc.)
  3. Check execution — Multiple verification checks are run against the document
  4. Status determination — An overall status is computed from individual check results
  5. 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

StatusDescription
initiatedVerification has been created and processing has started
passedAll required checks passed
failedOne or more required checks failed
requires_retryThe verification could not be completed — typically due to image quality issues. The applicant should retry with better images.
canceledThe verification was canceled

​
Understanding Checks

Each verification includes an array of checks — individual tests performed against the document. Every check has:
FieldDescription
nameIdentifier of the check (e.g., optical_mrz, status_optical)
statusResult: passed, failed, or not_applicable
requirementHow the check affects the overall result: required, not_required, or requires_retry
reasonsArray of reason strings if the check failed
metadataAdditional details about the check

​
Check Categories

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)
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
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
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.