Reference KYC
Verify users with your own KYC provider inside your app, then send SAVA a reference so SAVA can confirm the result and make the KYC decision.
Overview
Reference KYC (partner-initiated, SAVA-verified) lets you run identity verification with your own KYC provider, inside your own application, and then send SAVA a reference to the result. SAVA confirms that result with the provider itself and makes the KYC decision.
You run the verification; SAVA makes the decision. You keep full control of the onboarding experience, without sending users through a separate SAVA flow, while SAVA owns the compliance decision. SAVA never relies on unverified data from your side: it either fetches the result from the provider or checks the provider's signature on it.
You verify the user with your KYC provider and send SAVA the reference. SAVA confirms the result itself, by fetching it from your KYC provider (Smile ID, Sumsub) or by verifying its signatures (Datanamix), compares it with the user's SAVA profile and decides. The submission is acknowledged straight away; you read the decision with List Users or Get User.
Two ways Reference KYC works
How SAVA confirms the result depends on your provider:
| Provider pull | Signed payload | |
|---|---|---|
| How it works | You share a dedicated API key for your KYC provider account. You send SAVA the job reference, and SAVA pulls the result directly from your KYC provider. | You send SAVA your KYC provider's original responses with their signatures. SAVA verifies each signature before using the data. |
| You send | Your KYC provider's job reference | The job reference plus the signed responses |
| Setup | Share a dedicated (secondary) API key during onboarding, kept separate from your production key | No key to share |
Which way applies depends on your KYC provider: see Supported providers. Your partner account is configured for one KYC provider during onboarding. Requests that name a different provider are rejected.
Supported providers
SAVA currently supports these KYC providers for Reference KYC:
| KYC provider | provider value | How SAVA confirms the result |
|---|---|---|
| Smile ID | smile_id | Provider pull |
| Sumsub | sumsub | Provider pull |
| Datanamix | datanamix | Signed payload. See the Datanamix guide |
How it works
Create the user in SAVA
Create the user with a hosted session and keep the returned user_id. Make sure the user's ID number, date of birth, first name and last name are captured: SAVA compares them with the verified identity.
Verify the user with your provider
Run the verification in your own app, using your KYC provider. Keep the reference for the verification (job_id), and anything else your KYC provider needs you to send.
Submit the reference to SAVA
Call svc.user.{partner_id}.submit_kyc_reference with the user_id, your provider and the reference. See Submit a reference.
SAVA confirms the result and decides
SAVA pulls or verifies the provider result, checks it, and compares the verified identity with the user's SAVA profile. The user's KYC is then approved, rejected, or held for review by SAVA compliance.
Read the decision
Poll the user with List Users or Get User until kyc_status is approved or rejected. See Check the result.
Submit a reference
Subject: svc.user.<partner_id>.submit_kyc_reference
Permissions Required: write
Request
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | required | The SAVA user being verified (UUID) |
provider | string | required | Your configured KYC provider: smile_id, sumsub or datanamix. See Supported providers |
data.job_id | string | required | Your KYC provider's reference for this verification |
data.payload | object | optional | KYC provider-specific data. Required for signed-payload providers such as Datanamix |
Response
The response confirms that SAVA has received the submission. It is not the KYC decision.
| Field | Type | Description |
|---|---|---|
accepted | boolean | Always true when the submission was received |
user_id | string | The user the submission is for |
job_id | string | The reference SAVA recorded for this submission |
received_at | string | When SAVA received the submission (RFC 3339) |
status | string | Always "RECEIVED" |
Received is not approved
A successful response only confirms receipt. Problems with the provider data itself, such as an invalid signature or a failed check, don't return an error: they reject the user's KYC, with the reason in kyc_rejection_reason. Always check the result with List Users or Get User.
Possible Errors
These are returned on the request itself, and nothing is recorded against the user:
400 Bad Request: Reference KYC is not enabled, the provider is unsupported, your account has no KYC provider configured, or the provider doesn't match your configuration400 Bad Request:job_idis missing400 Bad Request: The user's KYC is already approved401 Unauthorized: Missing or invalid authentication404 Not Found: User not found
Check the result
The submit response only confirms receipt. To get the KYC decision, read the user with the User Service endpoints you already use:
List Users
svc.user.<partner_id>.list: every user in an entity, with their KYC status. Poll this after submitting.
Get User
svc.user.<partner_id>.get: one user, with their KYC status.
Poll until the user's kyc_status is approved or rejected. The KYC fields (kyc_status, verified, verified_at, kyc_submitted_at, kyc_reviewed_at, kyc_rejection_reason) are described with each endpoint.
What each status means
kyc_status | Meaning | What to do |
|---|---|---|
approved | The result was confirmed with your KYC provider and matches the user's profile. verified is true | Continue onboarding, for example request a card |
rejected | A check failed. kyc_rejection_reason says which | Fix the cause, then submit again |
pending | SAVA compliance is reviewing the user manually, for example because the user's profile is missing details needed for automatic approval | Keep polling |
You can submit again while a user is pending or after a rejection. Once a user is approved, further submissions are refused.
Provider guides
- Datanamix: the signed reports to send, and the checks SAVA runs.