Documentation/API/KYB API

KYB Service

The Know Your Business (KYB) API enables you to conduct business verification and due diligence processes through the Vertex platform.

VERTEX ENGINE

00

Table of Contents

  1. Get KYB
  2. Uploading Documents
  3. Submit KYB Documents

1. Get KYB

Retrieves the Know Your Business (KYB) information for a specific organisation.

Subject: svc.kyb.<partner_id>.get

Request

{
  "entity_id": "string"  // Required
}

Required Fields

  • entity_id

Response

{
  "entity_id": "string",
  "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": "string",
  "rejection_reason": "string"
}

Possible Errors

  • 400 Bad Request: If the request validation fails
  • 404 Not Found: If the KYB process for the given organisation 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:

Command Line Upload Method

Command Line Upload(bash)
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

Document Naming Convention

Documents must follow these naming patterns:

  • Business documents:
    • business_registration_<timestamp>
    • proof_of_address_<timestamp>
    • tax_verification_<timestamp>
  • Director documents:
    • director_proof_of_address_<director_id>_<timestamp>
    • director_selfie_<director_id>_<timestamp>
    • director_id_back_<director_id>_<timestamp>
    • director_id_front_<director_id>_<timestamp>

Example

Example Upload Command(bash)
xargs -I {} nats obj put --name={} kyb_dropbox_58f0b1b0-ffac-4e0c-805c-40dc141913f9 ./dummy.pdf << EOF
business_registration_1726220326
proof_of_address_1726220276
tax_verification_1726220240
director_proof_of_address_7aa53a6d5869c8145cee2af0f5d92aa5_1726220179
director_selfie_7aa53a6d5869c8145cee2af0f5d92aa5_1726220125
director_id_back_7aa53a6d5869c8145cee2af0f5d92aa5_1726220059
director_id_front_7aa53a6d5869c8145cee2af0f5d92aa5_1726220044
EOF

Programmatic Access (JavaScript)

For programmatic access, you can use the NATS client libraries:

Retrieve Bucket

Retrieve Bucket(javascript)
const os = await natsConn?.jetstream().views.os(`kyb_dropbox_${entityId}`);

Upload file

Upload File(javascript)
import { MsgHdrsImpl } from "nats.ws";
const headers = new MsgHdrsImpl();
headers.set("original_filename", file.name);
try{
    await os?.put(
        {
          name: `${name}_${moment().unix()}`, 
          headers,
        },
        this.fileToReadableStream(file)
    );
} catch (err) {
  // handle error
}

3. Submit KYB Documents

Submit KYB documents for verification.

Subject: svc.kyb.<partner_id>.submit

Request

{
  "entity_id": "string",     // Required
  "documents": [             // Required
    "string"
  ],
  "directors": {             // Required
    "<director_id>": [
      "string"
    ]
  }
}

Required Fields

  • entity_id
  • documents
  • directors

Response

{
  // Empty response indicates success
}

Possible Errors

  • 400 Bad Request: Invalid or incomplete data
  • 404 Not Found: Entity not found
  • 500 Internal Server Error: Error processing KYB submission
Previous: Entity APINext: Accounts