Skip to main content

​
What are Documents?

Documents represent the identity files that an applicant provides during verification. The Identity API supports two types of documents:
TypeResource TypePurpose
Government IDdocument/idvPassports, driver’s licenses, national IDs, and other government-issued identity documents
Proof of Addressdocument/addressUtility 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

StatusDescription
pendingDocument created, waiting for file upload
submittedFiles uploaded, document submitted for processing
processedProcessing complete, data extracted
failedProcessing 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.