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

# Identity API Overview

> Verify identities, manage accounts, and run document verifications with the Beltic Identity API.

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

<CardGroup cols={2}>
  <Card title="Accounts" icon="user" href="/guides/identity/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.
  </Card>

  <Card title="Sessions" icon="clipboard-list" href="/guides/identity/sessions">
    Where applicant information is collected. Sessions hold identity data — entered manually or extracted automatically from documents — and track the overall verification progress.
  </Card>

  <Card title="Documents" icon="id-card" href="/guides/identity/documents">
    Represent identity documents such as government IDs or proof of address. Documents are uploaded, processed, and their data is extracted for verification.
  </Card>

  <Card title="Verifications" icon="shield-check" href="/guides/identity/verifications">
    Run verification checks against documents. Each verification produces a set of checks with pass/fail results, giving you detailed insight into document authenticity.
  </Card>
</CardGroup>

## How It All Fits Together

A typical identity verification flow looks like this:

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

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

  <Step title="Upload Documents">
    Create a `document/idv` (for government IDs) or `document/address` (for proof of address) and upload the document images.
  </Step>

  <Step title="Run a Verification">
    Create a verification linked to the document. Beltic processes the document, runs authenticity checks, extracts data, and returns the results.
  </Step>

  <Step title="Make a Decision">
    Based on the verification results, approve or decline the session. The account status reflects the overall state of the applicant.
  </Step>
</Steps>

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

<Card title="Running a Document Verification" icon="bolt" href="/guides/identity/running-a-document-verification">
  Learn how to verify a government ID in 3 API calls — no SDK or session required.
</Card>

## JSON:API Format

All Identity API endpoints follow the [JSON:API specification](https://jsonapi.org/). Resources are returned in a consistent format:

```json theme={null}
{
  "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](/guides/authentication) for details.

```bash theme={null}
curl -X GET https://api.beltic.com/v1/identity/accounts \
  -H "X-Api-Key: YOUR_API_KEY"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Accounts" icon="arrow-right" href="/guides/identity/accounts">
    Learn how to create and manage accounts
  </Card>

  <Card title="Quick Verification" icon="arrow-right" href="/guides/identity/running-a-document-verification">
    Run your first document verification in minutes
  </Card>
</CardGroup>