Create a new verification session

curl --request POST \ --url http://127.0.0.1:8787/v1/sessions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "redirect_url": "<string>", "share_fields": {}, "webhook_endpoint_id": "<string>" } '

{ "data": { "id": "<string>", "nfc_tries_used": 1, "liveness_tries_used": 1, "contract_version": 123, "share_fields": {}, "redirect_url": "<string>", "webhook_endpoint_id": "<string>", "verification_url": "<string>", "expires_at": "<string>", "completed_at": "<string>", "created_at": "<string>", "updated_at": "<string>", "cancel_token": "<string>" }, "error": null }

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

redirect_url

string

Optional URL to redirect the user to after the verification session is completed. Must use https:// (http:// is only accepted for localhost in development).

Maximum string length: 2048

Optional map of requested share fields keyed by claim key. Each entry must include required (boolean) and reason (non-empty string, max 200).

Show child attributes

webhook_endpoint_id

Optional webhook endpoint ID or endpoint ID list to target for this session. When omitted, events fan out to every enabled subscribed endpoint.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9_-]+$

Response

Successful operation. Returns the newly created verification session.

data

object

required

Show child attributes

Example:

{
  "id": "vs_mza7vecksrtyfw193ekcvl5vnws3bt1lz96buu3iw7zidckf8dga2zx2echb3t16",
  "status": "created",
  "failure_code": null,
  "nfc_tries_used": 0,
  "liveness_tries_used": 0,
  "contract_version": 1,
  "share_fields": {
    "document_type_code": {
      "required": false,
      "reason": "Needed to know the document type code",
      "source": "rc"
    },
    "date_of_birth": {
      "required": true,
      "reason": "Needed to verify age eligibility",
      "source": "rc"
    },
    "kayle_document_id": {
      "required": true,
      "reason": "Sharing \"Kayle Document ID\"",
      "source": "default"
    }
  },
  "redirect_url": "https://example.com/redirect",
  "webhook_endpoint_id": null,
  "verification_url": "https://verify.kayle.id/vs_mza7vecksrtyfw193ekcvl5vnws3bt1lz96buu3iw7zidckf8dga2zx2echb3t16",
  "expires_at": "2025-01-01T00:00:00Z",
  "completed_at": null,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

error

null

required