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

Important

• Ensure accurate personal data (name, DOB, nationality, address) is collected to facilitate a smooth KYC process.
• A successful response includes a unique customer reference for tracking verification status.
• Customer Due Diligence (CDD) data is 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": "Transfers to/from Own Wallet",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-05-12",
    "nationality": "US",
    "contactinfo": {
      "email": "john.doe@example.com",
      "phonenumber": "+1234567890"
    },
    "address": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "postCode": "10001",
      "stateCode": "NY",
      "countryCode": "US"
    },
    "taxidentification": {
      "number": "123-45-6789",
      "taxResidenceCountryCode": "US"
    },
    "cdd": {
      "employmentStatus": "Salaried",
      "sof": "Salary / Employment Income",
      "pep": "Not a PEP",
      "expectedMonthlyvolumes": "EUR 500 - EUR 5,000"
    }
  },
  "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1"
}'

Request Body Parameters (Individual)

Response

{
  "reference": "f81a5b62-27b8-4b3b-b51e-eb10edeb1731",
  "status": "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.