Start

Quickstart in five minutes

Create a session from your server, send the user to the hosted flow, and get a signed webhook when it finishes.

Get an API key. In the admin, open Apps and choose New app. Copy the API key (and keep the app secret key for webhook verification). Store both in server-side environment variables, never in browser code.
Create a session. Call POST /api/session/init from your backend (next section).
Send the user to verificationUrl by redirect or iframe.
Receive the webhook at the URL you passed, and fetch the result.

Create a session

Authenticate with the x-api-key header. The body is JSON:

Field	Type	Notes
`clientId`	string, required	Your own identifier for the customer or tenant.
`flow`	"KYC" \| "KYB", required	Person or business verification.
`applicationId`	string, required	Your own reference (order id, user id). Returned in webhooks.
`webhook`	string, optional	Public HTTP(S) URL. Overrides the app default. Private addresses are rejected.
`language`	"en" \| "fr" \| "ar"	If omitted, detected from the browser.
`persistData`	boolean	false keeps extracted data in memory only. See the privacy guide.
`checkCINUniqueness`	boolean	Flag a card number already verified for your company.
`enableAmlCheck`	boolean	Screen the applicant against AML lists.

curl -X POST https://YOUR_HOST/api/session/init \
  -H "x-api-key: $KONNECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "acme",
    "flow": "KYC",
    "applicationId": "order-10293",
    "webhook": "https://acme.example/webhooks/konnect",
    "language": "en"
  }'

A successful call returns 201:

json

{
  "success": true,
  "session": { "sessionId": "b7c1…", "status": "INITIATED", "flow": "KYC", "applicationId": "order-10293", "…": "…" },
  "verificationUrl": "https://YOUR_HOST/verify/b7c1…/kyc",
  "resultPasskey": "9F3A21BC"
}

Keep session.sessionId with your own record. resultPasskey is the code a reviewer uses on the hosted result page; treat it as a credential.

Send the user to the flow

Redirect to verificationUrl (recommended). Iframe embedding only works if your deployment relaxes the default X-Frame-Options: DENY and camera policy headers. See the website guide and the mobile guide.

HTTPS requiredBrowsers only expose the camera on HTTPS pages (and on localhost). A production deployment must be served over HTTPS or the capture steps cannot start.

Receive the webhook

When the session reaches a decision or needs review, Konnect ID POSTs a signed JSON event to your webhook URL. Verify the signature, answer with a 2xx quickly, and process asynchronously. Full details in Webhooks.

Fetch the result

Use the same key to read the session. The response includes the session and, unless persistData is false and already consumed, the extracted application data.

curl https://YOUR_HOST/api/session/SESSION_ID/info \
  -H "x-api-key: $KONNECT_API_KEY"

Ephemeral sessionsWith persistData: false, application data is purged from memory after the first successful fetch. Store what you need on your side.

What if something fails?

See error codes and rate limits in the API reference, or the troubleshooting guide. To try everything without cloud credentials, use local mode.