> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beltic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifications

> Run verification checks against identity documents and understand the results.

## 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:

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

<Info>
  Verification creation is a **synchronous** operation. The response includes the full result — no polling required.
</Info>

## Creating a Verification

### With a Session and Document

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

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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

<Accordion title="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)
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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.
</Accordion>

### 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:

```bash theme={null}
# 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](/guides/identity/running-a-document-verification).