Creating a Customer (Individual) via API

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 UNSUCCESSFUL.

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.

🚧

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.

📘

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": "john.doe@example.com",
    "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

Verification Process

The flow progresses to PENDING_VERIFICATION while KYC checks are performed.
If a valid selfieVerifiedAt timestamp is provided, and other required verification steps (e.g. ID checks) pass, the customer can be marked as VERIFIED.

Retrieving Customer Status

Call GET /platform/v1/customers/{reference} to fetch the current verification status.
Or configure webhooks to get notifications when the verification result (approved or failed) is determined.
Possible Statuses

PENDING_AGREEMENTS: Awaiting agreement acceptance or additional info.
PENDING_VERIFICATION: Verification in progress.
VERIFIED: Customer successfully verified.
UNSUCCESSFUL: Verification failed; check details for specific reasons.