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

# Sessions

> Sessions collect applicant information and track the verification lifecycle from creation to decision.

## What is a Session?

A **Session** is where applicant information is collected and the verification process is tracked. Think of it as a verification case — it holds all the personal data, documents, and verification results for a single onboarding attempt.

Sessions are the central hub of the verification workflow:

* **Manual data entry**: You can set the applicant's name, date of birth, address, and other details directly on the session.
* **Automatic extraction**: When a document is verified, extracted data (name, DOB, address, etc.) can be automatically written back to the session.
* **Status tracking**: The session status reflects the overall progress of the verification — from creation through completion to a final decision.

## Session Statuses

Sessions follow a lifecycle represented by these statuses:

| Status              | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `created`           | Session has been created but no activity has occurred |
| `started`           | The applicant has begun the verification process      |
| `pending`           | Information has been submitted and is being processed |
| `completed`         | All verification steps are complete                   |
| `failed`            | The verification process failed                       |
| `marked_for_review` | The session requires manual review                    |
| `approved`          | A reviewer has approved the session                   |
| `declined`          | A reviewer has declined the session                   |
| `expired`           | The session expired before completion                 |

### Status Flow

```
created → started → pending → completed → approved
                                        → declined
                                        → marked_for_review → approved
                                                            → declined
                           → failed
         → expired
```

## Creating a Session

Create a session linked to an account:

```bash theme={null}
curl -X POST https://api.beltic.com/v1/identity/sessions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "session",
      "attributes": {
        "entity_type": "person"
      },
      "relationships": {
        "account": {
          "data": { "type": "account", "id": "acc_01HQ..." }
        }
      }
    }
  }'
```

### Response

```json theme={null}
{
  "data": {
    "type": "session",
    "id": "sess_01HQ...",
    "attributes": {
      "status": "created",
      "creator_type": "api",
      "entity_type": "person",
      "person": null,
      "business": null,
      "contact": null,
      "address": null,
      "identity_numbers": null,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "started_at": null,
      "expires_at": null,
      "completed_at": null,
      "failed_at": null,
      "marked_for_review_at": null,
      "decisioned_at": null,
      "expired_at": null,
      "redacted_at": null
    },
    "relationships": {
      "account": {
        "data": { "type": "account", "id": "acc_01HQ..." }
      },
      "documents": { "data": [] },
      "verifications": { "data": [] },
      "session_device": { "data": null }
    }
  }
}
```

## Populating Session Data

You can provide applicant information in two ways:

### Manual Input

Update the session directly with applicant details:

```bash theme={null}
curl -X PATCH https://api.beltic.com/v1/identity/sessions/{session_id} \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "session",
      "id": "sess_01HQ...",
      "attributes": {
        "person": {
          "name": { "first": "Jane", "last": "Doe" },
          "birth_date": "1990-05-15"
        },
        "address": {
          "line1": "123 Main St",
          "city": "San Francisco",
          "subdivision": "CA",
          "postal_code": "94102",
          "country_code": "US"
        },
        "contact": {
          "email": "jane@example.com",
          "phone": "+1234567890"
        }
      }
    }
  }'
```

### Automatic Extraction from Documents

When you create a verification with `auto_update_session` set to `true`, extracted data from the document is automatically written to the session:

```json theme={null}
{
  "data": {
    "type": "verification/idv",
    "relationships": {
      "document": { "data": { "type": "document/idv", "id": "doc_01HQ..." } },
      "session": { "data": { "type": "session", "id": "sess_01HQ..." } }
    },
    "meta": {
      "auto_update_session": true
    }
  }
}
```

When the verification completes, the session's `person` fields (name, date of birth, etc.) are populated from the document data — saving you from having to manually copy the information.

<Info>
  Both `document/idv` (government ID) and `document/address` (proof of address) verifications can auto-update the session when linked.
</Info>

## Making Decisions

Once verification is complete, you can approve or decline the session:

<Tabs>
  <Tab title="Approve">
    ```bash theme={null}
    curl -X POST https://api.beltic.com/v1/identity/sessions/{session_id}/approve \
      -H "X-Api-Key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Decline">
    ```bash theme={null}
    curl -X POST https://api.beltic.com/v1/identity/sessions/{session_id}/decline \
      -H "X-Api-Key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

These actions require the `sessions:decide` permission on your API key.

## Expiring a Session

If a session is no longer needed or has been idle for too long, you can expire it:

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

## Listing Sessions

Retrieve sessions with optional filters:

```bash theme={null}
# List all sessions for an account
curl -X GET "https://api.beltic.com/v1/identity/sessions?filter[account_id]=acc_01HQ..." \
  -H "X-Api-Key: YOUR_API_KEY"
```

## Redacting a Session

Remove all personal data from a session:

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

<Warning>
  Redaction is irreversible. All personal data on the session will be permanently removed.
</Warning>

## Relationships

Sessions connect to:

* **Account** — The account this session belongs to
* **Documents** — All documents uploaded during this session (`document/idv`, `document/address`)
* **Verifications** — All verification results for this session
* **Session Device** — Device information if the session was started from a client device

## Next Steps

With a session created, you can now [upload documents](/guides/identity/documents) and [run verifications](/guides/identity/verifications) against them.