Introduction
Quick start
This guide describes the minimum steps to launch user verification through KnowaKYC. After four steps, you have a fully working integration: from creating a verification scenario to receiving results.
Step 1. Get access to the platform
- Obtain credentials for the KnowaKYC admin panel (provided by your account manager or during sign-up).
- Sign in to the admin panel.
- Open the API keys section and create a KYC-type API key:
- Environment: select
testfor development orlivefor production. - Scopes: select the required permissions (for the quick start,
*is recommended for full access).
- Environment: select
- Save the key secret — it is shown once. The secret is required to compute the HMAC signature when calling the API.
Important. The key secret (with the
sk_prefix) must stay on the server side. Never expose it to the client.
Step 2. Create a verification flow
Open the Flows section in the admin panel:
- From a template (recommended): open the Template gallery and choose a ready-made scenario, for example "Standard KYC" (document + selfie + liveness) or "Basic KYC" (document only).
- From scratch: click "Create flow" and add the steps you need in the visual editor: document upload, selfie, liveness check, OTP, AML screening, manual review, etc.
After configuration, publish the flow. Copy the flow identifier (flow_id) — you need it for the next step.
Step 3. Create a verification link
You can create a verification link in two ways:
Option A. Via the Tenant API (recommended for integration)
Send a request from the server side, signed with HMAC:
POST
ApiKeyAuthheader
Authorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Link options (flow_id required)
application/json- body
expires_in?integerseconds
external_reference?stringexternal_user_id?stringflow_id?stringlocale?stringmetadata?prefilled?redirect_url?stringutm_campaign?stringutm_medium?stringutm_source?stringCreated or reused link
application/json- response
data?success?booleancurl -X POST 'https://example.com/tenant/v1/kyc/verification-links' \ -H 'X-Timestamp: string' \ -H 'Content-Type: application/json' \ -d '{}'Example Response
{ "success": true, "data": { "created_at": "string", "delivery_eligible": true, "expires_at": "string", "external_reference": "string", "external_user_id": "string", "flow_id": "string", "id": "string", "link_url": "string", "locale": "string", "qr_code_url": "string", "redirect_url": "string", "reuse_reason": "external_reference", "reused": true, "session_id": "string", "session_resumable": true, "session_status": "string", "short_url": "string", "status": "string", "url": "string", "verification_link": "string", "verification_url": "string" }}Key request parameters:
| Parameter | Required | Description |
|---|---|---|
flow_id | Yes | Identifier of the published verification flow |
external_user_id | No (recommended) | User identifier in your system. Lets you link the verification result back to your user |
redirect_url | No | URL to redirect to after verification completes |
locale | No | UI language (en, ru) |
expires_in | No | Link lifetime in seconds (defaults to the flow configuration) |
Computing the HMAC signature: the algorithm is described, with JavaScript and Go examples, in the Authentication section.
The response returns the verification link URL. Deliver it to the user by email, SMS, messenger, or in your application's customer portal.
Option B. Via the admin panel (for testing)
Open the Verification links section and click "Create link":
- Choose the published flow.
- Optionally set
external_user_id,redirect_url, and the lifetime. - Copy the generated link and open it in your browser to run a test verification.
Step 4. Register a webhook to receive results
To receive verification results in real time, configure a webhook:
- Open the Webhooks section of the admin panel.
- Click "Create endpoint".
- Enter the URL of your server where KnowaKYC sends notifications.
- Select event types — to start, subscribe to:
verification.approved— verification approvedverification.declined— verification declinedverification.needs_review— verification routed to manual review
- Save the webhook secret (with the
whsec_prefix) — you need it to verify the authenticity of incoming notifications.
Signature verification: every webhook carries an
X-Onekyc-Signatureheader with an HMAC-SHA256 signature. For details, see Webhooks.
Alternative — query via the API:
GET
ApiKeyAuthheader
Authorization<token>HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.
limit?integerLimit (1-100, default 50)
offset?integerOffset (default 0)
status?stringFilter by verification status
Value in
"pending""verified""rejected""review"X-Timestamp*stringUnix timestamp (seconds, max 5 min drift)
Applicants list
application/json- response
data?array<>pagination?success?booleancurl -X GET 'https://example.com/tenant/v1/kyc/applicants' \ -H 'X-Timestamp: string'Example Response
{ "pagination": { "has_more": true, "limit": 0, "next_cursor": "string", "offset": 0, "total": 0 }, "success": true, "data": [ { "address": "string", "aml_decision": "string", "aml_risk_score": 0, "avatar_photo_url": "string", "avatar_url": "string", "client_liveness_score": 0, "created_at": "string", "current_review_decision": { "client_message": "string", "created_at": "string", "decision": "string", "id": "string", "reason_codes": [ "string" ], "scope": "string", "session_id": "string", "step_id": "string" }, "date_of_birth": "string", "details": { "address": { "city": "string", "country": "string", "full_text": "string", "localized": { "property1": { "property1": "string", "property2": "string" }, "property2": { "property1": "string", "property2": "string" } }, "postal_code": "string", "region": "string", "street": "string" }, "barcode": { "fields": { "property1": "string", "property2": "string" }, "raw": "string", "type": "string" }, "document": { "booklet_number": "string", "class": "string", "issuing_authority": "string", "issuing_place": "string", "issuing_state_code": "string", "mrz_type": "string", "series": "string" }, "localized": { "property1": { "property1": "string", "property2": "string" }, "property2": { "property1": "string", "property2": "string" } }, "mrz": { "document_code": "string", "fields": { "property1": "string", "property2": "string" }, "issuing_state": "string", "raw": "string" }, "personal": { "additional_fields": { "property1": "string", "property2": "string" }, "nationality_name": "string", "personal_number": "string", "profession": "string", "tax_number": "string" }, "provider": { "duration_ms": 0, "evidence_reuse": { "execution_id": "string", "reason": "string", "recovery_audit_id": "string", "source_attempt_number": 0, "source_execution_id": "string", "source_verification_id": "string" }, "name": "string", "raw": { "property1": null, "property2": null }, "raw_response_key": "string", "received_at": "string", "request_id": "string", "version": "string" } }, "doc_liveness_score": 0, "document_back_key": "string", "document_back_url": "string", "document_front_key": "string", "document_front_url": "string", "document_number": "string", "document_photo_key": "string", "document_photo_url": "string", "document_type": "string", "email": "string", "enrichment": { "scope": "string", "summary": { "bankruptcy_confirmed": true, "call_statuses": { "property1": "string", "property2": "string" }, "completed_at": "string", "hard_block_reason": "string", "match_count": 0, "merged_decision": "string", "merged_risk_score": 0, "observed_at": "string", "passport_invalid": true, "status": "string" } }, "enrichment_errors": [ "string" ], "expiry_date": "string", "expiry_status": "string", "external_id": "string", "face_match_score": 0, "first_name": "string", "full_name": "string", "full_name_latin": "string", "full_name_native": "string", "full_name_original": "string", "id": "string", "issuing_country": "string", "issuing_state_code": "string", "last_name": "string", "last_session_id": "string", "last_verified_at": "string", "latest_flow_name": "string", "liveness_mode": "string", "liveness_score": 0, "localized": { "property1": { "property1": "string", "property2": "string" }, "property2": { "property1": "string", "property2": "string" } }, "middle_name": "string", "name_source": { "property1": null, "property2": null }, "nationality": "string", "phone": "string", "photo_url_expires_at": "string", "portrait_photo_key": "string", "portrait_photo_url": "string", "risk_score": 0, "risk_signals": { "property1": null, "property2": null }, "selfie_photo_key": "string", "selfie_photo_url": "string", "session_summary": { "approved": 0, "in_progress": 0, "rejected": 0, "review": 0, "total": 0 }, "updated_at": "string", "verification_score": 0, "verification_status": "pending" } ]}Done
The integration is complete. When the user opens the verification link, they go through the flow on the KnowaKYC page, and your server receives the result through the webhook.
Next steps
- Authentication — HMAC signature details, key types, scopes
- Webhooks — full event list, payload format, signature verification, retry policy
- Applicants — fetching verification data, documents, AML results
- Verification links — link lifecycle, batch creation, QR codes
- Flows — configure verification scenarios via the API
- KYB API — business (legal entity) verification
- Errors and limits — error codes, rate limits
- API reference (OpenAPI) — interactive reference for all endpoints