Skip to main content

​
What is the Identity API?

The Beltic Identity API provides a complete toolkit for identity verification and KYC (Know Your Customer) workflows. It lets you onboard users, collect and verify identity documents, and make decisions on applicants — all through a single, consistent API. Whether you need to verify a government-issued ID, collect proof of address, or manage the lifecycle of an applicant, the Identity API gives you the building blocks to do it programmatically.

​
Core Resources

The Identity API is built around four key resources that work together:

Accounts

Represent an external entity (a person or business) in your system. Use accounts to correlate your users with Beltic, track their verification status, and perform actions like blocking.

Sessions

Where applicant information is collected. Sessions hold identity data — entered manually or extracted automatically from documents — and track the overall verification progress.

Documents

Represent identity documents such as government IDs or proof of address. Documents are uploaded, processed, and their data is extracted for verification.

Verifications

Run verification checks against documents. Each verification produces a set of checks with pass/fail results, giving you detailed insight into document authenticity.

​
How It All Fits Together

A typical identity verification flow looks like this:
1

Create an Account

Create an account to represent the user in your system. You can store an external_id to link it back to your own database.
2

Create a Session

Create a session linked to the account. The session collects all the applicant’s personal information (name, date of birth, address, etc.).
3

Upload Documents

Create a document/idv (for government IDs) or document/address (for proof of address) and upload the document images.
4

Run a Verification

Create a verification linked to the document. Beltic processes the document, runs authenticity checks, extracts data, and returns the results.
5

Make a Decision

Based on the verification results, approve or decline the session. The account status reflects the overall state of the applicant.

​
API-Only Document Verification

If you don’t need the full session-based flow, you can also run standalone document verifications entirely through the API. This is useful when you already have document images and just need to verify them.

Running a Document Verification

Learn how to verify a government ID in 3 API calls — no SDK or session required.

​
JSON:API Format

All Identity API endpoints follow the JSON:API specification. Resources are returned in a consistent format: 
{
  "data": {
    "type": "account",
    "id": "acc_01HQ...",
    "attributes": {
      "status": "active",
      "external_id": "user-123",
      "entity_type": "person",
      "person": {
        "name": { "first": "Jane", "last": "Doe" }
      }
    },
    "relationships": {
      "sessions": {
        "data": [{ "type": "session", "id": "sess_01HQ..." }]
      }
    }
  }
}
Key conventions:
  • type identifies the resource kind (account, session, document/idv, verification/idv, etc.)
  • attributes contains the resource data
  • relationships links to related resources
  • meta carries additional request/response metadata (e.g., presigned URLs, pagination)

​
Authentication

All requests require an API key passed via the X-Api-Key header. See Authentication for details. 
curl -X GET https://api.beltic.com/v1/identity/accounts \
  -H "X-Api-Key: YOUR_API_KEY"

​
Next Steps

Accounts

Learn how to create and manage accounts

Quick Verification

Run your first document verification in minutes