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

# Documents

> Upload and manage identity documents such as government IDs and proof of address.

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

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

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

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

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

<Tip>
  For two-sided documents (e.g., driver's licenses), add both front and back images as separate files.
</Tip>

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

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

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

```bash theme={null}
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](/guides/identity/verifications) to run checks against the document. See [Running a Document Verification](/guides/identity/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](/guides/identity/verifications) to check their authenticity and extract identity data.