Before you start
You need a KayWhySee account. Your account admin can invite you from Organisation → Team in the dashboard.
Create an API key
In the dashboard, open Developers → API keys and create a key. It starts with kyc_live_ and is shown once, so copy it somewhere safe. Keep it on your server: anyone with it can start verifications on your account.
export KAYWHYSEE_API_KEY="kyc_live_..."Start a verification
Create a session with your own reference for the customer, such as their user ID. Add a redirect_url to bring them back to your app when they're done.
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();
console.log(session.start_url);import os
import requests
response = 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,
)
response.raise_for_status()
session = response.json()
print(session["start_url"])The response is the new session, plus its start_url:
{
"id": "a841ce23-0c9d-42a4-ba95-3e7e17a1407b",
"reference": "user_1042",
"status": "created",
"start_url": "https://www.kaywhysee.com/s/KcMfm5BgDccsti3hTZZsT-MbfbePrUqzw0KiR3i4zrM",
"expires_at": "2026-10-16T12:10:11Z"
}Send your customer to the start_url
Redirect them to it from your sign-up flow, or send it by email or message. It's for one verification and lasts 24 hours.
Open it yourself to try it. On a computer you'll see a QR code: scan it with your phone, agree to the check, photograph an ID and record the short selfie.
The link is for one person. Don't share one link between customers: create a session for each.
Read the result
Fetch the session with its id. Its status tells you where it's got to, and outcome holds the decision once there is one.
curl https://www.kaywhysee.com/api/v1/sessions/$SESSION_ID \
-H "Authorization: Bearer $KAYWHYSEE_API_KEY"In production, use webhooks to hear about decisions as they happen, instead of polling.