Sessions

A session represents a single identity verification attempt for one end-user.

Create a session

POST /v1/sessions · Header: x-api-key

Field	Type	Required	Description
`country`	string	✅	ISO 3166-1 alpha-3 (e.g. `COD`)
`flow`	`"user"` \| `"business"`	✅	Flow type
`tier`	`"tier1"` \| `"tier2"` \| `"tier3"`	✅	Assurance level
`external_user_reference`	string	❌	Your internal user ID
`redirect_url`	string	❌	Post-verification redirect
`metadata`	object	❌	Custom key-value data

POST

/v1/sessions

curl -X POST http://localhost:3002/v1/sessions \
  -H "x-api-key: sk_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "COD",
    "flow": "user",
    "tier": "tier2",
    "external_user_reference": "user_123"
  }'

Response

{
  "session_id": "ses_01hzabc123",
  "verify_url": "http://localhost:3005/verify/tok_xyz",
  "status": "created",
  "required_steps": ["consent", "id_document", "liveness"],
  "expires_at": "2026-06-01T12:00:00Z"
}

Other endpoints

Method	Path	Description
`GET`	`/v1/sessions`	List sessions
`GET`	`/v1/sessions/:id`	Get session
`DELETE`	`/v1/sessions/:id`	Cancel session
`POST`	`/v1/sessions/:id/submit`	Submit for processing
`GET`	`/v1/sessions/:id/result`	Get decision

Session statuses

Status	Description
`created`	Initialized, awaiting user
`collecting`	User started the flow
`processing`	AI review in progress
`approved`	Verified
`rejected`	Failed
`review_required`	Manual review
`expired`	TTL exceeded
`cancelled`	Cancelled by tenant