This endpoint enables you to create business (company) customers. Once a customer is created, we initiate verification. You can then retrieve the customer object or listen to webhooks (coming soon) to track the status change from PENDING_AGREEMENTS to VERIFIED or REJECTED.

Important

• Gathering and validating customer data (IDs, address proofs, etc.) before creating the customer is crucial for a smooth KYC/KYB flow.
• A successful customer creation returns a CustomerReference you will use to track verification status.
• Documents are not uploaded in this request. They must be added separately via a dedicated documents endpoint.

🚧

BETA endpoint

Please note that this endpoint is currently in beta, and it may undergo changes as we continue to improve and refine the functionality.

📘

Idempotency supported endpoint

This means you can retry a request without worrying about it being processed multiple times.

To use this feature, add the X-Idempotency-Key header with a unique value (a UUID). This ensures the request is only processed once, even if it's sent multiple times.

Endpoints

Create a Business (Company) Customer

Use this to create a business (company) customer. You can associate multiple beneficial owners, controlling persons, and signers (often referred to collectively as “associates”).

Request

Example – business customer creation with associates:

curl --location 'https://api.sandbox.bvnk.com/platform/v1/customers' \
--header 'X-Idempotency-Key: 0b3ed172-e24f-43f5-a901-4f7b6d138ebe' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="YourHawkID", ts="1728655954", nonce="MdPBLt", mac="jGEwZvz7rVO3lM3Ose8Ww1PtgnsHBe7eFph3Nzj5H6Y="' \
--data-raw '{
  "type": "COMPANY",
  "company": {
    "name": "The Walt Disney Company",
    "description": "Entertainment business",
    "taxResidenceCountryCode": "US",
    "registrationNumber": "26-4532998",
    "industryCode": "74101",
    "address": {
      "addressLine1": "500 S Buena Vista St",
      "city": "Burbank",
      "postalCode": "91521",
      "state": "CA",
      "countryCode": "US"
    },
    "associates": [
      {
        "person": {
          "firstName": "Donald",
          "lastName": "Duck",
          "dateOfBirth": "1908-11-29",
          "address": {
            "addressLine1": "1313 Webfoot Street",
            "city": "Duckburg",
            "postalCode": "4587",
            "state": "CA",
            "countryCode": "US"
          },
          "contactInfo": {
            "emailAddress": "donald.duck@disney.com"
          },
          "taxIdentification": {
            "number": "384-37-3429",
            "taxResidenceCountryCode": "US"
          }
        },
        "title": "COO",
        "riskScore": "MEDIUM",
        "controls": {
          "hasOwnership": true,
          "hasControl": false,
          "isSigner": true
        }
      }
    ]
  },
  "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1",
  "riskScore": "LOW"
}'

Request Body Parameters (Company)

Response

Success Example:

{
  "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
  "status": "PENDING"
}

Failure Example:

{
  "code": "ACCOUNTS-2000",
  "status": "BAD_REQUEST",
  "message": "Invalid request",
  "details": {
    "errors": {
      "industryReference": [
        "Industry with reference: 56e65ebc-06fa-11ef-bbf8-02d3d923cf2b does not exist"
      ]
    }
  }
}

Add Documents to a Customer

Use this endpoint to attach documents to an existing customer—either at the company level or for a specific associate (beneficial owner, director, or signer). Each call uploads a single document. Call the endpoint multiple times if you need to attach more than one file.

Important

• Make sure to reference the correct customerReference.
• Use personReference when the document belongs to a specific associate. If omitted (or null), the document is attached at the company level for business customers.
• Files must be base64-encoded before sending.

Endpoint

Request

Example – uploading a document for an associate:

curl --location --request PUT 'https://api.sandbox.bvnk.com/platform/v1/customers/123e4567-e89b-12d3-a456-426614174000/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="YourHawkID", ts="1678900000", nonce="abc123", mac="xyz789..."' \
--data-raw '{
  "personReference": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab",
  "type": "PASSPORT",
  "name": "John Smith ID.pdf",
  "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
}'

Path Parameter

Request Body Parameters

Response

Success Example:

{
  "reference": "d42e1c62-27b8-4b3b-b51e-eb10edeb1731",
  "message": "Document uploaded successfully.",
  "status": "ACCEPTED"
}

Failure Example:

{
  "code": "DOCUMENTS-4000",
  "status": "BAD_REQUEST",
  "message": "Invalid document content",
  "details": {
    "errors": {
      "content": [
        "Document file content is not valid base64"
      ]
    }
  }
}

Good to know

1. Check Document Status

   • Once uploaded, we run checks on the document. You can retrieve the customer or associated person object to see if it’s recognised.

2. Retain Document References

   • The reference returned in the success response may be used for future queries or audits.

3. Combine with KYC

   • Document verification may be necessary before the customer can move from PENDING_VERIFICATION to VERIFIED.

Verification & Next Steps

1. Verification Process
   Once created, the customer enters a PENDING_AGREEMENTS (or similar) state while we wait for required agreements and checks. After that, verification may proceed in a PENDING_VERIFICATION state until KYC/KYB is complete. The time to verify can vary from seconds to hours, depending on risk profiles and document completeness.

2. Retrieving Customer Status

   • GET /platform/v1/customers/{reference} to fetch the current status.
   • Or configure BVNK webhooks to receive updates when a verification result is determined.

3. Possible Statuses

   • PENDING_AGREEMENTS: Awaiting agreement acceptance or further inputs.
   • PENDING: Verification in progress.
   • VERIFIED: Customer has been verified.
   • REJECTED: Customer has been rejected during verification. see details for more info.