Sessions

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:

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

{
  "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:

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:

{
  "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.

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

Making Decisions

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

Approve
Decline

curl -X POST https://api.beltic.com/v1/identity/sessions/{session_id}/approve \
  -H "X-Api-Key: YOUR_API_KEY"

curl -X POST https://api.beltic.com/v1/identity/sessions/{session_id}/decline \
  -H "X-Api-Key: YOUR_API_KEY"

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:

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:

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

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

Redaction is irreversible. All personal data on the session will be permanently removed.

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 and run verifications against them.

Overview

Workflow API

Credentials API

Document API

Identity API (Legacy)

What is a Session?

Session Statuses

Status Flow

Creating a Session

Response

Populating Session Data

Manual Input

Automatic Extraction from Documents

Making Decisions

Expiring a Session

Listing Sessions

Redacting a Session

Relationships

Next Steps

​What is a Session?

​Session Statuses

​Status Flow

​Creating a Session

​Response

​Populating Session Data

​Manual Input

​Automatic Extraction from Documents

​Making Decisions

​Expiring a Session

​Listing Sessions

​Redacting a Session

​Relationships

​Next Steps

What is a Session?

Session Statuses

Status Flow

Creating a Session

Response

Populating Session Data

Manual Input

Automatic Extraction from Documents

Making Decisions

Expiring a Session

Listing Sessions

Redacting a Session

Relationships

Next Steps