API References

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

{
  "entity_id": "uuid"  // Required
}
FieldTypeRequiredDescription
entity_idstring (uuid)requiredThe unique identifier of the entity to retrieve KYB information for

Response

{
  "entity_id": "uuid",
  "documents": [
    {
      "key": "string",
      "doc_type": "string",
      "rejection_reason": "string",
      "approved": boolean
    }
  ],
  "directors": [
    {
      "id": "string",
      "name": "string",
      "approved": boolean,
      "verified": boolean,
      "documents": [
        {
          "key": "string",
          "doc_type": "string",
          "rejection_reason": "string",
          "approved": boolean
        }
      ],
      "verification_sent": boolean,
      "id_type": "string",
      "metadata": {
        "key": "value"
      }
    }
  ],
  "metadata": {},
  "state": "pending",                  // pending | approved | rejected
  "rejection_reason": "string"
}
FieldTypeDescription
entity_idstringUUID of the entity this KYB record belongs to
documentsarrayBusiness documents submitted for verification, each with a storage key, document type, approval flag, and rejection reason if declined
directorsarrayDirectors retrieved from Transunion, each with identity details, approval and verification flags, and their own submitted documents
metadataobjectAdditional metadata for the KYB record
statestringCurrent KYB state: pending, approved or rejected. See KYB states
rejection_reasonstringWhy 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:

stateMeaningWhat to do
pendingKYB has started and is not yet approved. This is the state when the business entity is created, and while SAVA reviews the documents you submitUpload and submit the documents, then poll Get KYB
approvedSAVA has reviewed and approved the KYB. The business account can now be openedContinue onboarding
rejectedSAVA has rejected the KYB. rejection_reason says why, and each document has its own approved flag and rejection_reasonFix the cause, upload new documents and submit again
State transitions
pending ──► approved     SAVA approves the KYB
pending ──► rejected     SAVA rejects the KYB, with a reason
rejected ──► pending     you submit documents again
approved ──► pending     SAVA revokes the approval

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 fails
  • 404 Not Found: If the KYB process for the given entity is not found
  • 500 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

PatternDocument
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
Upload documents
xargs -I {} nats obj put --name={} kyb_dropbox_<entity_id> ./document.pdf << EOF
business_registration_<timestamp>
proof_of_address_<timestamp>
tax_verification_<timestamp>
director_proof_of_address_<director_id>_<timestamp>
director_selfie_<director_id>_<timestamp>
director_id_back_<director_id>_<timestamp>
director_id_front_<director_id>_<timestamp>
EOF

3. Submit KYB Documents

Submit KYB documents for verification.

Subject: svc.kyb.<partner_id>.submit

Request

{
  "entity_id": "<uuid>",                                // string (uuid): Required
  "documents": [                                        // string[]: Object storage keys of business documents
    "business_registration_<timestamp>",                // <document_type>_<timestamp>
    "proof_of_address_<timestamp>",
    "tax_verification_<timestamp>"
  ],
  "directors": {                                        // object<uuid, string[]>: director_id maps to array of document keys
    "<director_id>": [                                  // uuid (without hyphens)
      "director_id_front_<director_id>_<timestamp>",    // <document_type>_<director_id>_<timestamp>
      "director_id_back_<director_id>_<timestamp>",
      "director_selfie_<director_id>_<timestamp>",
      "director_proof_of_address_<director_id>_<timestamp>"
    ]
  }
}
FieldTypeRequiredDescription
entity_idstring (uuid)requiredThe unique identifier of the entity to submit KYB documents for
documentsstring[]requiredObject storage keys of business documents
directorsobject<uuid, string[]>requiredMaps 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

{
  // Empty response indicates success
}

Possible Errors

  • 400 Bad Request: Invalid or incomplete data
  • 400 Bad Request: invalid KYB process state, when the KYB is already approved (see KYB states)
  • 404 Not Found: Entity not found
  • 500 Internal Server Error: Error processing KYB submission

On this page