Documents

What are Documents?

Documents represent the identity files that an applicant provides during verification. The Identity API supports two types of documents:

Type	Resource Type	Purpose
Government ID	`document/idv`	Passports, driver’s licenses, national IDs, and other government-issued identity documents
Proof of Address	`document/address`	Utility bills, bank statements, or other documents that prove a residential address

Each document can be used standalone (for direct API-based verification) or within a session (as part of a full verification flow).

Document IDV (`document/idv`)

A document/idv represents a government-issued identity document. When processed through a verification, the system extracts personal data (name, date of birth, document number, etc.) and runs authenticity checks.

Creating a Document IDV

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

The response includes presigned upload URLs for uploading document images:

{
  "data": {
    "type": "document/idv",
    "id": "doc_01HQ...",
    "attributes": {
      "status": "pending",
      "document_type": null,
      "files": [],
      "front_side": null,
      "back_side": null,
      "portrait": null,
      "signature": null,
      "created_at": "2025-01-15T10:30:00Z",
      "submitted_at": null,
      "processed_at": null
    },
    "relationships": {
      "session": {
        "data": { "type": "session", "id": "sess_01HQ..." }
      }
    }
  }
}

Adding Files to a Document

Upload document images by adding files:

curl -X POST https://api.beltic.com/v1/identity/documents/idvs/{document_id}/files \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "document/idv",
      "attributes": {
        "filename": "front.jpg",
        "content_type": "image/jpeg",
        "byte_size": 245000
      }
    }
  }'

This returns a presigned URL you can use to upload the actual file:

curl -X PUT "{presigned_upload_url}" \
  -H "Content-Type: image/jpeg" \
  --data-binary @front.jpg

For two-sided documents (e.g., driver’s licenses), add both front and back images as separate files.

Document IDV Statuses

Status	Description
`pending`	Document created, waiting for file upload
`submitted`	Files uploaded, document submitted for processing
`processed`	Processing complete, data extracted
`failed`	Processing failed

Extracted Data

After processing through a verification, the document is enriched with extracted data:

Personal info: Name, date of birth, birth place, sex, nationality
Document details: Document number, type, class, issue/expiry dates, issuing authority, issuing country
Address: Full address extracted from the document
Images: Cropped front side, back side, portrait photo, and signature images

Document Address (`document/address`)

A document/address represents a proof of address document. The flow is similar to document/idv:

curl -X POST https://api.beltic.com/v1/identity/documents/addresses \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "document/address",
      "relationships": {
        "session": {
          "data": { "type": "session", "id": "sess_01HQ..." }
        }
      }
    }
  }'

After adding files, submit the document for processing:

curl -X POST https://api.beltic.com/v1/identity/documents/addresses/{document_id}/submit \
  -H "X-Api-Key: YOUR_API_KEY"

Standalone Documents

Documents can be created without a session. This is useful when you want to verify a document through the API without the full session-based flow:

curl -X POST https://api.beltic.com/v1/identity/documents/idvs \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "document/idv"
    }
  }'

You can then use the Verifications API to run checks against the document. See Running a Document Verification for a complete walkthrough.

File Requirements

Supported formats: JPEG, PNG
Recommended resolution: At least 300 DPI for best extraction accuracy
File size: Maximum 10MB per file
Quality tips:
- Ensure the entire document is visible with no cropping
- Avoid glare, shadows, and blurriness
- Place the document on a contrasting background

Next Steps

Once your documents are uploaded, run a verification to check their authenticity and extract identity data.

Overview

Workflow API

Credentials API

Document API

Identity API (Legacy)

What are Documents?

Document IDV (`document/idv`)

Creating a Document IDV

Adding Files to a Document

Document IDV Statuses

Extracted Data

Document Address (`document/address`)

Standalone Documents

File Requirements

Next Steps

​What are Documents?

​Document IDV (document/idv)

​Creating a Document IDV

​Adding Files to a Document

​Document IDV Statuses

​Extracted Data

​Document Address (document/address)

​Standalone Documents

​File Requirements

​Next Steps

What are Documents?

Document IDV (`document/idv`)

Creating a Document IDV

Adding Files to a Document

Document IDV Statuses

Extracted Data

Document Address (`document/address`)

Standalone Documents

File Requirements

Next Steps