Skip to main content

​
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:
StatusDescription
createdSession has been created but no activity has occurred
startedThe applicant has begun the verification process
pendingInformation has been submitted and is being processed
completedAll verification steps are complete
failedThe verification process failed
marked_for_reviewThe session requires manual review
approvedA reviewer has approved the session
declinedA reviewer has declined the session
expiredThe 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: 
curl -X POST https://api.beltic.com/v1/identity/sessions/{session_id}/approve \
  -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.