Create a session · KayWhySee Docs

Creates a session for one of your customers and returns it with a start_url. Send your customer to that URL to verify. The URL is for one verification and lasts 24 hours; once your customer has started on a phone, it stays with that phone.

edit_note

One open session per reference

If the reference already has a session that hasn't finished (created, handed_off, capturing, submitted or processing), you get that session back with a new start_url, and the earlier link stops working. Calling again, after a page refresh or a double click, never makes a second one. Once a session has finished, the next call makes a new one.

link Authorization

Authorization string header required

Your secret key, as Bearer kyc_live_.... The key needs the sessions:create scope.

link Body

reference string required

Your ID for the customer, 1 to 200 characters, such as a user or account ID. Sessions with the same reference are grouped together in the dashboard.

Don't use names or email addresses.

redirect_url string

An absolute http or https URL, up to 500 characters. When your customer finishes, they get a button back to it. Arriving at it proves nothing: read the session to find out what happened.

documents object[]

The documents your customer may choose from. Each one must be accepted in the workspace's settings. Omit to offer all of them.

add Show properties

type string required

passport, driving_licence, id_card or residence_permit.

country string

The issuing country, as an ISO 3166-1 alpha-3 code such as GBR. Omit for every country. A passport is any country's: its MRZ says which, and document_country on the session reports it once the document is checked.

link Response

Returns 201 Created with the session object and one extra field:

start_url string

The link that starts the verification. It's only returned here: we keep a hash of it, not the link itself, so store it if you need to send it again.

link Errors

Status	Code	When
`400`	`VALIDATION_ERROR`	`reference` missing or too long, `redirect_url` not a valid URL, or a `documents` entry the workspace doesn't accept
`401`	`AUTHENTICATION_ERROR`	Missing, invalid or revoked key
`403`	`AUTHORIZATION_ERROR`	The key doesn't have the `sessions:create` scope

curl -X POST https://www.kaywhysee.com/api/v1/sessions \ -H "Authorization: Bearer $KAYWHYSEE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reference": "user_1042", "redirect_url": "https://your-app.example/verified" }'

const response = await fetch("https://www.kaywhysee.com/api/v1/sessions", { method: "POST", headers: { Authorization: `Bearer ${process.env.KAYWHYSEE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ reference: "user_1042", redirect_url: "https://your-app.example/verified", }), }); const session = await response.json();

import os import requests session = requests.post( "https://www.kaywhysee.com/api/v1/sessions", headers={"Authorization": f"Bearer {os.environ['KAYWHYSEE_API_KEY']}"}, json={ "reference": "user_1042", "redirect_url": "https://your-app.example/verified", }, timeout=10, ).json()

{ "id": "a841ce23-0c9d-42a4-ba95-3e7e17a1407b", "reference": "user_1042", "status": "created", "outcome": null, "reasons": [], "reviewed": false, "review": null, "retry_session_id": null, "retry_of": null, "checks": {}, "document_type": null, "document_country": null, "captures": {}, "created_at": "2026-10-15T12:10:11Z", "expires_at": "2026-10-16T12:10:11Z", "submitted_at": null, "decided_at": null, "start_url": "https://www.kaywhysee.com/s/KcMfm5BgDccsti3hTZZsT-MbfbePrUqzw0KiR3i4zrM" }

link Authorization

link Body

link Response

link Errors

Confirm

Enter Value