Skip to main content
POST
/
v1
/
sessions
Create session
curl --request POST \
  --url https://api.example.com/v1/sessions

​
Request

curl -X POST https://identity.contra.id/v1/sessions \
  -H "x-api-key: $CONTRA_KEY" -H "Content-Type: application/json" \
  -d '{
    "workflow_id":  "enhanced_kyc",
    "vendor_data":  "user-abc-123",
    "callback":     "https://yourapp.com/contra/webhook",
    "expected_details": { "first_name": "Mikayla" }
  }'

​
Parameters

FieldTypeRequiredDescription
workflow_idstringyesWhich workflow to run.
vendor_datastringyesYour own user id. Idempotency key with workflow_id.
callbackurlnoPer-session webhook URL.
metadataobjectnoOpaque JSON echoed back on the decision.
contact_detailsobjectno{ email?, phone? } — pre-fill OTP steps.
expected_detailsobjectnoExpected name / DOB / country — triggers mismatch warnings.

​
Response · 201

{
  "session_id": "sess_b3f1c2a4",
  "url":        "https://verify.contra.id/sess_b3f1c2a4",
  "status":     "pending",
  "workflow_id": "enhanced_kyc",
  "vendor_data": "user-abc-123",
  "created_at":  1716900000,
  "expires_at":  1716986400,
  "idempotent_reuse": false
}
Send the user to url. Poll GET /v1/sessions/:id or wait for the webhook.

​
Idempotency

Posting twice with the same (workflow_id, vendor_data) while a session is pending/in_progress/in_review returns the existing session with idempotent_reuse: true.