KYB Service
The Know Your Business (KYB) API enables you to conduct business verification and due diligence processes through the SAVA platform.
1. Get KYB
Retrieves the Know Your Business (KYB) information for a specific entity.
Subject: svc.kyb.<partner_id>.get
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string (uuid) | required | The unique identifier of the entity to retrieve KYB information for |
Response
| Field | Type | Description |
|---|---|---|
entity_id | string | UUID of the entity this KYB record belongs to |
documents | array | Business documents submitted for verification, each with a storage key, document type, approval flag, and rejection reason if declined |
directors | array | Directors retrieved from Transunion, each with identity details, approval and verification flags, and their own submitted documents |
metadata | object | Additional metadata for the KYB record |
state | string | Current KYB state: pending, approved or rejected. See KYB states |
rejection_reason | string | Why SAVA rejected the KYB. Populated when state is rejected, and cleared when you resubmit documents |
Director details from Transunion
The Get KYB endpoint retrieves director details from Transunion. These details will be used when uploading and submitting KYB documents after the business entity has been created.
KYB states
The state field shows where the business entity is in KYB:
state | Meaning | What to do |
|---|---|---|
pending | KYB has started and is not yet approved. This is the state when the business entity is created, and while SAVA reviews the documents you submit | Upload and submit the documents, then poll Get KYB |
approved | SAVA has reviewed and approved the KYB. The business account can now be opened | Continue onboarding |
rejected | SAVA has rejected the KYB. rejection_reason says why, and each document has its own approved flag and rejection_reason | Fix the cause, upload new documents and submit again |
KYB is approved manually
KYB is not auto-approved. SAVA approves it only after reviewing every required business and director document, so a KYB stays pending until that review is complete.
You can submit or change documents only while the KYB is pending or rejected. Once it is approved, submissions are refused with 400 Bad Request.
Possible Errors
400 Bad Request: If the request validation fails404 Not Found: If the KYB process for the given entity is not found500 Internal Server Error: For any unexpected errors during processing
2. Uploading Documents
Documents are uploaded to the KYB dropbox using NATS object storage. You can upload multiple documents at once using the command line as shown below:
Unique Documents Required Per Director
When you fetch the KYB information and retrieve 2 directors, you must upload unique documents for each director (not the same documents twice). For X number of directors, you need to upload X sets of director-specific documents. This is required for compliance regulations.
Document naming convention
| Pattern | Document |
|---|---|
business_registration_<timestamp> | Business registration |
proof_of_address_<timestamp> | Business proof of address |
tax_verification_<timestamp> | Business tax verification |
director_id_front_<director_id>_<timestamp> | Director ID, front |
director_id_back_<director_id>_<timestamp> | Director ID, back |
director_selfie_<director_id>_<timestamp> | Director selfie |
director_proof_of_address_<director_id>_<timestamp> | Director proof of address |
3. Submit KYB Documents
Submit KYB documents for verification.
Subject: svc.kyb.<partner_id>.submit
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string (uuid) | required | The unique identifier of the entity to submit KYB documents for |
documents | string[] | required | Object storage keys of business documents |
directors | object<uuid, string[]> | required | Maps each director_id to an array of that director's uploaded document keys |
Note
The documents array contains the exact object storage keys (names) you used when uploading to kyb_dropbox_<entity_id> (see Document naming convention). Similarly, the directors object maps each director's ID to their uploaded document keys.
Response
Possible Errors
400 Bad Request: Invalid or incomplete data400 Bad Request:invalid KYB process state, when the KYB is alreadyapproved(see KYB states)404 Not Found: Entity not found500 Internal Server Error: Error processing KYB submission