> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecontra.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Create session

> Start a verification session for one of your users.

## Request

```bash theme={null}
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

| Field              | Type   | Required | Description                                                 |
| ------------------ | ------ | -------- | ----------------------------------------------------------- |
| `workflow_id`      | string | **yes**  | Which workflow to run.                                      |
| `vendor_data`      | string | **yes**  | Your own user id. Idempotency key with `workflow_id`.       |
| `callback`         | url    | no       | Per-session webhook URL.                                    |
| `metadata`         | object | no       | Opaque JSON echoed back on the decision.                    |
| `contact_details`  | object | no       | `{ email?, phone? }` — pre-fill OTP steps.                  |
| `expected_details` | object | no       | Expected name / DOB / country — triggers mismatch warnings. |

## Response · 201

```json theme={null}
{
  "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`.