Sessions
Understanding verification sessions in Bouncer
Sessions
A session in Bouncer represents a single age verification attempt. Understanding the session lifecycle is crucial for integrating Bouncer effectively.
Session Lifecycle
Status Flow
CREATED → PENDING → VERIFICATION_STARTED → COMPLETED
↓
VERIFICATION_KYC → COMPLETEDSession Statuses
| Status | Description |
|---|---|
CREATED | Session created via API, user not yet redirected |
PENDING | User has visited the verification page |
VERIFICATION_STARTED | User has begun the liveness check |
VERIFICATION_KYC | User is performing ID document scanning |
COMPLETED | Verification finished (check success field for result) |
CANCELLED | Session was cancelled |
Session Parameters
When creating a session, you can configure:
| Parameter | Required | Description |
|---|---|---|
age_target | Yes | Target age to verify (8, 13, 16, 18, 21, 25, or 30) |
redirect_url | Yes | Where to send the user after verification |
webhook_url | No | URL to receive real-time status updates |
force_kyc | No | Always require ID verification |
metadata | No | Custom data to attach (e.g., order ID) |
expiration_time | No | Session timeout in seconds (60-3600) |
See the Create Session API for complete request/response details.
Session Expiration
Sessions have a configurable expiration time:
- Default: 300 seconds (5 minutes)
- Minimum: 60 seconds
- Maximum: 3600 seconds (1 hour)
Expired sessions cannot be completed. If a user's session expires, you'll need to create a new one.
Verification Flow
Age Estimation Flow
- User visits verification page
- Liveness check is performed
- System estimates age from facial features
- If estimated age ≥ target age → SUCCESS
- If estimated age < target age → Redirect to KYC
KYC Flow
When KYC is required (age estimation failed or force_kyc: true):
- User captures ID document (front and back)
- System verifies document and extracts birth date
- Age calculated from document birth date
- If age ≥ target age AND all checks pass → SUCCESS
- Otherwise → FAILURE
Failure Reasons
When a session fails, common reasons include:
| Reason | Description |
|---|---|
underage | User's verified age is below the target |
face_mismatch | Face doesn't match ID photo |
spoofed_document | Fake or digital ID detected |
liveness_failed | Liveness check failed |
Polling vs Webhooks
You can check session results two ways:
Polling
Query the Get Session Status API periodically until status is completed.
Webhooks (Recommended)
Configure a webhook_url when creating the session to receive real-time notifications. See Webhooks for details.
Best Practices
- Always set a redirect_url: Users need somewhere to go after verification
- Use webhooks for production: More reliable than polling
- Handle expiration gracefully: Provide users a way to restart verification
- Store session IDs: Map sessions to your internal user/order IDs
- Validate success server-side: Never trust client-side success indicators