Skip to main content
POST
/
v1
/
sessions
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": {}
}
'
{
  "data": {
    "id": "<string>",
    "status": "created",
    "contract_version": 123,
    "share_fields": {},
    "redirect_url": "<string>",
    "verification_url": "<string>",
    "expires_at": "<string>",
    "completed_at": "<string>",
    "created_at": "<string>",
    "updated_at": "<string>",
    "cancel_token": "<string>",
    "attempts": [
      {
        "id": "<string>",
        "session_id": "<string>",
        "status": "in_progress",
        "failure_code": "session_expired",
        "risk_score": 0.5,
        "completed_at": "<string>",
        "created_at": "<string>",
        "updated_at": "<string>"
      }
    ]
  },
  "error": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.kayle.id/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
include_attempts
boolean | null

When true, includes the attempts array on the created session. Attempts will be empty on creation.

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).

​
share_fields
object

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

Response

Successful operation. Returns the newly created verification session.

​
data
object
required
Example:
{
  "id": "vs_mza7vecksrtyfw193ekcvl5vnws3bt1lz96buu3iw7zidckf8dga2zx2echb3t16",
  "status": "created",
  "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",
  "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
object
required