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

EnvironmentEndpoint
ProductionPOST https://api.bvnk.com/platform/v1/customers
SandboxPOST https://api.sandbox.bvnk.com/platform/v1/customers

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)

AttributeTypeRequiredDescription
typestringYesMust be INDIVIDUAL.
individualobjectYesContainer object for individual customer details.
individual.riskScorestringNoThe risk rating for this individual, e.g., LOW, MEDIUM, HIGH.
individual.descriptionstringNoShort descriptive text about the individual (e.g., "Private client").
individual.firstNamestringYesThe individual’s given/first name.
individual.lastNamestringYesThe individual’s family/last name.
individual.dateOfBirthstringYesDate of birth in YYYY-MM-DD format.
individual.birthCountryCodestringNoISO 2-letter code of the country where the individual was born, e.g., US.
individual.nationalitystringNo*The individual’s nationality, e.g., US. Depending on compliance, this may be required.
individual.emailstringNoThe individual’s email address.
individual.addressobjectYesPhysical address details for the individual.
individual.address.addressLine1stringYesFirst line of the street address.
individual.address.addressLine2stringNoSecond line of the address (optional).
individual.address.citystringYesCity or locality.
individual.address.postCodestringYesZIP or postal code.
individual.address.countryCodestringYesISO 2-letter code for the country, e.g., US.
individual.identificationobjectNoOptional object containing identification details.
individual.identification.documentNumberstringNoPassport or other official ID number.
individual.identification.taxNumberstringNoTax ID (e.g., SSN or TIN).
individual.identification.selfieVerifiedAtstringNoISO 8601 date-time if selfie/liveness check has been done externally (e.g., 2025-01-01T10:00:00Z).
individual.eddobjectNoPlaceholder for enhanced due diligence (EDD) data.
individual.edd.expectedMonthlyVolumesstringNoCode or reference for expected monthly transaction volume.
individual.edd.employmentStatusstringNoEmployment status, e.g., EMPLOYED, UNEMPLOYED, RETIRED, etc.
individual.edd.lastOccupationstringNoLatest or primary occupation.
individual.edd.intermediarybooleanNoWhether the individual acts as an intermediary (e.g., broker or agent) in transactions.
signed_agreement_idstringYesReference to an e-sign or terms acceptance.

Response

Response CodeDescription
202Successful operation.
400Bad request.
{
  "reference": "f81a5b62-27b8-4b3b-b51e-eb10edeb1731",
  "status": "VERIFICATION_PENDING"
}
AttributeTypeDescription
referencestringA unique identifier for the customer.
statusstringThe current status of the customer.
Possible values include:

- PENDING_AGREEMENTS - pending customer agreement consent,
- INFO_REQUIRED - customer information is needed for verification,
- PENDING- pending customer verification,
- VERIFIED - customer has been verified,
- REJECTED - verification has been unsuccessful.

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.