Sessions

A session represents a single verification attempt. Every interaction with Verifa starts by creating a session — it tracks the user through capture, processing, and the final decision.

Session lifecycle

pending → capturing → processing → completed
                                 → under_review
                                 → awaiting_external
          ↓
        expired

Statuses

Terminal vs. active statuses

Active: pending, capturing, processing, awaiting_external, under_review, sandbox_pending

Terminal: completed, expired, failed

Once a session reaches a terminal status, its result is final and cannot change (except through manual review of under_review sessions).

Creating a session

$
curl -X POST https://api.withverifa.com/api/v1/sessions \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "external_ref": "user_abc123",
>
    "country": "US",
>
    "workflow_id": "workflow_custom_kyc",
>
    "metadata": {
>
      "plan": "premium",
>
      "signup_source": "mobile"
>
    },
>
    "redirect_url": "https://your-app.com/verify/complete"
>
  }'

Request parameters

Response

1
{
2
  "id": "session_abc123",
3
  "status": "pending",
4
  "capture_url": "https://app.withverifa.com/verify/tok_...",
5
  "qr_code_data_url": "data:image/png;base64,...",
6
  "is_sandbox": false,
7
  "created_at": "2026-02-01T12:00:00Z",
8
  "expires_at": "2026-02-01T12:20:00Z"
9
}

The capture_url contains a single-use token that expires after 20 minutes. The qr_code_data_url is a base64-encoded PNG of the capture URL, useful for displaying a QR code for mobile users.

Listing sessions

$
curl "https://api.withverifa.com/api/v1/sessions?status=completed&limit=25&offset=0" \
>
  -H "X-API-Key: vk_live_your_key_here"

Filters

Response

1
{
2
  "data": [...],
3
  "pagination": {
4
    "total": 142,
5
    "limit": 25,
6
    "offset": 0
7
  }
8
}

Retrieving a session

$
curl https://api.withverifa.com/api/v1/sessions/session_abc123 \
>
  -H "X-API-Key: vk_live_your_key_here"

Returns the full session object including status, metadata, tags, and linked review case information.

Session operations

Resume an expired session

Re-issue a capture token for an expired or abandoned session:

$
curl -X POST https://api.withverifa.com/api/v1/sessions/session_abc123/resume \
>
  -H "X-API-Key: vk_live_your_key_here"

Returns a new capture_url with a fresh token. The original documents and progress are preserved.

Expire a session manually

Force-expire an active session:

$
curl -X POST https://api.withverifa.com/api/v1/sessions/session_abc123/expire \
>
  -H "X-API-Key: vk_live_your_key_here"

Reprocess a session

Re-run the verification workflow on a completed session:

$
curl -X POST https://api.withverifa.com/api/v1/sessions/session_abc123/reprocess \
>
  -H "X-API-Key: vk_live_your_key_here"

Useful after updating workflow rules — the original documents are re-evaluated against the current workflow configuration.

Update metadata

$
curl -X PATCH https://api.withverifa.com/api/v1/sessions/session_abc123 \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "external_ref": "updated_user_id",
>
    "metadata": { "tier": "gold" }
>
  }'

View documents

Retrieve signed URLs for the uploaded documents:

$
curl https://api.withverifa.com/api/v1/sessions/session_abc123/documents \
>
  -H "X-API-Key: vk_live_your_key_here"

1
{
2
  "data": [
3
    {
4
      "doc_type": "id_front",
5
      "mime_type": "image/jpeg",
6
      "url": "https://api.withverifa.com/.../id_front?expires=...&sig=...",
7
      "expires_in": 300
8
    },
9
    {
10
      "doc_type": "selfie",
11
      "mime_type": "image/jpeg",
12
      "url": "https://api.withverifa.com/.../selfie?expires=...&sig=...",
13
      "expires_in": 300
14
    }
15
  ]
16
}

Document URLs are HMAC-signed and expire after 5 minutes (configurable). See Data Access for details.

View risk assessment

$
curl https://api.withverifa.com/api/v1/sessions/session_abc123/risk \
>
  -H "X-API-Key: vk_live_your_key_here"

Returns the fraud signal assessment including risk score, risk level, and triggered signals. See Fraud Signals for details.

Session result

The session result is a separate object containing the verification outcome. Fetch it after the session reaches completed or under_review:

$
curl https://api.withverifa.com/api/v1/sessions/session_abc123/result \
>
  -H "X-API-Key: vk_live_your_key_here"

Result statuses

Session redaction

Delete all PII and document images for a session:

$
curl -X DELETE https://api.withverifa.com/api/v1/sessions/session_abc123/data \
>
  -H "X-API-Key: vk_live_your_key_here"

Redaction is permanent and irreversible. See Data Retention for automatic retention policies and GDPR compliance.

Webhooks

Sessions fire these webhook events:

Related

• Verifications & Checks — What checks run during a session
• Workflows — How verification steps are orchestrated
• Identities — How sessions link to persistent identity records