API ReferencesKYC Service

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.

3 · SAVA confirms the result, one of two waysorKYC providerSmile ID, Sumsub, DatanamixYour appSAVAsvc.user.*1 · verify the user in your appresult + job_id2 · submit_kyc_referenceprovider pull: fetch the result with your API keyRECEIVED (acknowledgment)5 · List Users / Get Userkyc_status: approved · rejected · pendingsigned payload: verify the signatures4 · compare with the user, decide

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 pullSigned payload
How it worksYou 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 sendYour KYC provider's job referenceThe job reference plus the signed responses
SetupShare a dedicated (secondary) API key during onboarding, kept separate from your production keyNo 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 providerprovider valueHow SAVA confirms the result
Smile IDsmile_idProvider pull
SumsubsumsubProvider pull
DatanamixdatanamixSigned 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

Request
{
  "user_id": "6486d903-9ae9-4c6c-be4e-febddb6496fc",
  "provider": "<your-kyc-provider>",
  "data": {
    "job_id": "job_abc_123",
    "payload": { }
  }
}
FieldTypeRequiredDescription
user_idstringrequiredThe SAVA user being verified (UUID)
providerstringrequiredYour configured KYC provider: smile_id, sumsub or datanamix. See Supported providers
data.job_idstringrequiredYour KYC provider's reference for this verification
data.payloadobjectoptionalKYC 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.

Response
{
  "accepted": true,
  "user_id": "6486d903-9ae9-4c6c-be4e-febddb6496fc",
  "job_id": "job_abc_123",
  "received_at": "2026-08-13T12:00:06.300Z",
  "status": "RECEIVED"
}
FieldTypeDescription
acceptedbooleanAlways true when the submission was received
user_idstringThe user the submission is for
job_idstringThe reference SAVA recorded for this submission
received_atstringWhen SAVA received the submission (RFC 3339)
statusstringAlways "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 configuration
  • 400 Bad Request: job_id is missing
  • 400 Bad Request: The user's KYC is already approved
  • 401 Unauthorized: Missing or invalid authentication
  • 404 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:

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_statusMeaningWhat to do
approvedThe result was confirmed with your KYC provider and matches the user's profile. verified is trueContinue onboarding, for example request a card
rejectedA check failed. kyc_rejection_reason says whichFix the cause, then submit again
pendingSAVA compliance is reviewing the user manually, for example because the user's profile is missing details needed for automatic approvalKeep 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.