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 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.
Environment | Endpoint |
---|---|
Production | POST https://api.bvnk.com/platform/v1/customers |
Sandbox | POST 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)
Attribute | Type | Required | Description |
---|---|---|---|
type | string | Yes | Must be INDIVIDUAL . |
individual | object | Yes | Container object for individual customer details. |
individual.riskScore | string | No | The risk rating for this individual, e.g., LOW , MEDIUM , HIGH . |
individual.description | string | No | Short descriptive text about the individual (e.g., "Private client"). |
individual.firstName | string | Yes | The individual’s given/first name. |
individual.lastName | string | Yes | The individual’s family/last name. |
individual.dateOfBirth | string | Yes | Date of birth in YYYY-MM-DD format. |
individual.birthCountryCode | string | No | ISO 2-letter code of the country where the individual was born, e.g., US . |
individual.nationality | string | No* | The individual’s nationality, e.g., US . Depending on compliance, this may be required. |
individual.email | string | No | The individual’s email address. |
individual.address | object | Yes | Physical address details for the individual. |
individual.address.addressLine1 | string | Yes | First line of the street address. |
individual.address.addressLine2 | string | No | Second line of the address (optional). |
individual.address.city | string | Yes | City or locality. |
individual.address.postCode | string | Yes | ZIP or postal code. |
individual.address.countryCode | string | Yes | ISO 2-letter code for the country, e.g., US . |
individual.identification | object | No | Optional object containing identification details. |
individual.identification.documentNumber | string | No | Passport or other official ID number. |
individual.identification.taxNumber | string | No | Tax ID (e.g., SSN or TIN). |
individual.identification.selfieVerifiedAt | string | No | ISO 8601 date-time if selfie/liveness check has been done externally (e.g., 2025-01-01T10:00:00Z ). |
individual.edd | object | No | Placeholder for enhanced due diligence (EDD) data. |
individual.edd.expectedMonthlyVolumes | string | No | Code or reference for expected monthly transaction volume. |
individual.edd.employmentStatus | string | No | Employment status, e.g., EMPLOYED , UNEMPLOYED , RETIRED , etc. |
individual.edd.lastOccupation | string | No | Latest or primary occupation. |
individual.edd.intermediary | boolean | No | Whether the individual acts as an intermediary (e.g., broker or agent) in transactions. |
signed_agreement_id | string | Yes | Reference to an e-sign or terms acceptance. |
Response
Response Code | Description |
---|---|
202 | Successful operation. |
400 | Bad request. |
{
"reference": "f81a5b62-27b8-4b3b-b51e-eb10edeb1731",
"status": "VERIFICATION_PENDING"
}
Attribute | Type | Description |
---|---|---|
reference | string | A unique identifier for the customer. |
status | string | The 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
-
Verification Process
Once created, the customer enters aPENDING_AGREEMENTS
(or similar) state while we wait for required agreements and checks. After that, verification may proceed in aPENDING
state until KYC/KYB is complete. The time to verify can vary from seconds to hours, depending on risk profiles and document completeness. -
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.
- GET
-
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. seedetails
for more info.
Updated 9 days ago