This endpoint enables you to create individual customers. Once a customer is created, we initiate the KYC verification process. You can then either poll the customer object or listen for webhooks to track the status change from PENDING_AGREEMENTS → VERIFIED or REJECTED.

Important

• Collecting accurate personal data (name, DOB, ID numbers, address) before creating the individual customer is crucial for a smooth KYC process.
• A successful creation response includes a unique reference for the customer, which you will use to track their verification status.
• By providing selfieVerifiedAt value, you confirm that the customer’s selfie check has already been performed and passed (removing the need for an additional liveness check).
• You must include enhanced due diligence (EDD) data if required.

🚧

Early Access

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

📘

Prerequisites

You will need to collect information about the customer before proceeding with the request to create one.

📘

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.

Create Customer Request

curl --location 'https://api.sandbox.bvnk.com/platform/v1/customers' \
--header 'X-Idempotency-Key: 86b5f133-9ee8-4f67-8747-7c9d0894a68b' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="YourHawkID", ts="1728655954", nonce="abc123", mac="..."' \
--data-raw '{
  "type": "INDIVIDUAL",
  "individual": {
    "riskScore": "LOW",
    "description": "Private client",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-05-12",
    "birthCountryCode": "US",
    "nationality": "US",
    "email": "[email protected]",
    "address": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "postCode": "10001",
      "countryCode": "US"
    },
    "identification": {
      "documentNumber": "AB1234567",
      "taxNumber": "123-45-6789",
      "selfieVerifiedAt": "2025-01-01T10:00:00Z"
    },
    "edd": {
      "expectedMonthlyVolumes": "86b5f133-9ee8-4f67-8747-7c9d0894a68b", 
      "employmentStatus": "EMPLOYED", 
      "lastOccupation": "Software Engineer",
      "intermediary": false
    }
  },
  "signed_agreement_id": "78eedde1-2402-4a59-8bbd-ccecb6d612d1"
}'

The details supplied to the create a Company entity customer

Request Body Parameters (Individual)

Response

{
  "reference": "f81a5b62-27b8-4b3b-b51e-eb10edeb1731",
  "status": "VERIFICATION_PENDING"
}

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 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.
   • INFO_REQUIRED: Customer information is needed for verification.
   • PENDING: Verification in progress.
   • VERIFIED: Customer has been verified.
   • REJECTED: Customer has been rejected during verification. see details for more info.