KYC Service
API reference for the Know Your Customer (KYC) verification process for users.
1. Introduction to KYC
Know Your Customer (KYC) is a critical process for verifying the identity of users. The KYC process is integrated into the user aggregate and affects the user's verified status.
Already verify users with your own KYC provider?
Use Reference KYC: you run the verification in your own app, send SAVA a reference, and SAVA confirms the result with the provider and makes the KYC decision.
KYC Process Flow
Approval is terminal and sets verified: true on the user. A rejected KYC can be resubmitted, which moves the status back to pending.
2. KYC Status and User Verification
KYC Statuses
The system tracks KYC progress through the following statuses:
| Value | Status | Description |
|---|---|---|
0 | not_started | Initial status, no KYC documents uploaded |
1 | pending | KYC documents uploaded, awaiting review |
2 | approved | KYC documents reviewed and approved |
3 | rejected | KYC documents reviewed and rejected |
User Verification
The verified field on the user aggregate indicates whether a user has completed KYC verification:
verified: false: User has not completed KYC verificationverified: true: User has successfully completed KYC verification (KYC status isapproved)
The verifiedAt timestamp is set when KYC is approved.
3. Document Upload to NATS Object Storage
KYC documents should be uploaded to NATS object storage before submitting the verification request. The API is storage-agnostic and accepts document storage keys from any storage solution, but NATS object storage is recommended for consistency across the platform.
Document Naming Convention
Documents should follow these naming patterns for consistency:
| Pattern | Document |
|---|---|
kyc_id_front_<user_id>_<timestamp> | Front of ID document |
kyc_id_back_<user_id>_<timestamp> | Back of ID document (if applicable) |
kyc_passport_<user_id>_<timestamp> | Passport (if using passport instead of ID) |
kyc_proof_of_residence_<user_id>_<timestamp> | Proof of residence (utility bill, bank statement, etc.) |
Command Line Upload Method
Programmatic Access
4. Submitting KYC Documents
After uploading documents to your storage solution, submit the document references to initiate the verification process.
Subject: svc.user.<partner_id>.upload_kyc_documents
Permissions Required: write
Request
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | required | UUID of the user |
id_document | string | optional | Storage key for ID document |
proof_of_residence | string | optional | Storage key for proof of residence |
Important Notes
- At least one document must be provided (either
id_documentorproof_of_residence) - Both documents can be provided, but only one is required
- The storage keys should reference documents already uploaded to your storage solution
- Documents can be re-uploaded if KYC is in
pendingorrejectedstatus
Example Request:
Response
Effects
- KYC status transitions from
not_startedtopending kycSubmittedAttimestamp is set- Emits
KYCDocumentsUploadedevent - Documents are stored in the user aggregate's
kycDocumentsmap
Possible Errors
400 Bad Request: Missing Documents
Returned when no documents are provided.
400 Bad Request: Already Verified
Returned when the user is already verified or KYC is already approved.
5. Querying User Information
Get User
Retrieves a single user by user ID, including KYC status and verification details.
Subject: svc.user.<partner_id>.get
Permissions Required: read
Request
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | required | UUID of the user to retrieve |
Response
KYC Fields
| Field | Type | Description |
|---|---|---|
verified | boolean | Whether the user is currently KYC verified. True when kyc_status is approved, false when not_started, pending, or rejected. Use kyc_status for the detailed lifecycle status, and verified as the simple approved/not-approved flag. |
kyc_status | string | Current KYC status. One of: not_started, pending, approved, rejected. |
kyc_submitted_at | string | Timestamp when KYC was submitted. Omitted if KYC has not been submitted. |
kyc_reviewed_at | string | Timestamp when KYC was approved or rejected. Omitted while KYC is pending or not started. |
kyc_rejection_reason | string | Reason for rejection. Only populated when kyc_status is rejected. |
List Users
Retrieves a list of users, including KYC status and verification details. Can be filtered by entity ID.
Subject: svc.user.<partner_id>.list
Permissions Required: read
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | optional | Filter results by entity |
Response
KYC Fields
| Field | Type | Description |
|---|---|---|
verified | boolean | Whether the user is currently KYC verified. True when kyc_status is approved, false when not_started, pending, or rejected. Use kyc_status for the detailed lifecycle status, and verified as the simple approved/not-approved flag. |
kyc_status | string | Current KYC status. One of: not_started, pending, approved, rejected. |
kyc_submitted_at | string | Timestamp when KYC was submitted. Omitted if KYC has not been submitted. |
kyc_reviewed_at | string | Timestamp when KYC was approved or rejected. Omitted while KYC is pending or not started. |
kyc_rejection_reason | string | Reason for rejection. Only populated when kyc_status is rejected. |