Creating a Customer (Business) via API
This endpoint enables you to create business (company) customers. Once a customer is created, we initiate verification. You can then retrieve the customer object or listen to webhooks (coming soon) to track the status change from PENDING_AGREEMENTS
to VERIFIED
or REJECTED
.
How Embedded Partner Customer creation works
Embedded Wallets allow Embedded Partners (EP) to offer seamless payment and fund management capabilities directly within their platform while maintaining their branding. This guide provides a step-by-step process to create Embedded Partner Customer (EPC) accounts utilising Embedded Wallets via the BVNK Portal.
This product is available to businesses (with support for Consumers / Individuals coming soon) based in the US, UK, EEA, and other countries supported by BVNK outside of these regions.
EPC State transition diagram
The creation and verification lifecycle of an EPC follows a series of states—Pending Agreements, Info Required, Pending, Verified, and Rejected—which are illustrated and explained in this section.
Understanding these states (and how an EPC transitions between them) is key to a smooth onboarding process.
- Pending Agreements
- The EPC has been created but must consent to BVNK’s Terms of Service.
- An agreements link is generated and must be shared with the EPC to collect consent.
- Info Required
- After Terms are signed, BVNK requires additional verification information (KYB/KYC).
- A verification link is provided for the EP to provide their Customer's (EPC) data and documents.
- Pending
- Once verification flow is submitted, BVNK performs compliance checks.
- During this time, you can monitor the EPC’s status in the portal.
- Verified
- The EPC has successfully passed the compliance review.
- Wallets can now be created and used.
- Rejected
- The EPC has failed compliance checks or provided invalid information.
- The flow halts unless additional data is requested and submitted for reconsideration.

Important
- Gathering and validating customer data (IDs, address proofs, etc.) before creating the customer is crucial for a smooth KYC/KYB flow.
- A successful customer creation returns a
CustomerReference
you will use to track verification status. - Documents are not uploaded in this request. They must be added separately via a dedicated documents endpoint.
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.
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.
Endpoints
Environment | Endpoint |
---|---|
Production | POST https://api.bvnk.com/platform/v1/customers |
Sandbox | POST https://api.sandbox.bvnk.com/platform/v1/customers |
Create a Business (Company) Customer
Use this to create a business (company) customer. You can associate multiple beneficial owners, controlling persons, and signers (often referred to collectively as “associates”).
Request
Example – business customer creation with associates:
curl --location 'https://api.sandbox.bvnk.com/platform/v1/customers' \
--header 'X-Idempotency-Key: 0b3ed172-e24f-43f5-a901-4f7b6d138ebe' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="YourHawkID", ts="1728655954", nonce="MdPBLt", mac="jGEwZvz7rVO3lM3Ose8Ww1PtgnsHBe7eFph3Nzj5H6Y="' \
--data-raw '{
"type": "COMPANY",
"company": {
"name": "The Walt Disney Company",
"description": "Entertainment business",
"entityType": "CORPORATION",
"taxResidenceCountryCode": "US",
"registrationNumber": "26-4532998",
"industryReference" : "30ea5818-06d8-11ef-b6e1-027612b7f6b5",
"monthlyExpectedVolumesReference" : "ef779c41-547e-11ef-8b9c-027612b7f6b5",
"address": {
"addressLine1": "500 S Buena Vista St",
"city": "Burbank",
"postalCode": "91521",
"state": "CA",
"countryCode": "US"
},
"associates": [
{
"person": {
"firstName": "Donald",
"lastName": "Duck",
"dateOfBirth": "1908-11-29",
"address": {
"addressLine1": "1313 Webfoot Street",
"city": "Duckburg",
"postalCode": "12345",
"state": "CA",
"countryCode": "US"
},
"contactInfo": {
"emailAddress": "[email protected]"
},
"taxIdentification": {
"number": "384-37-3429",
"taxResidenceCountryCode": "US"
}
},
"titles": ["BUSINESS_OWNER", "DIRECTOR"]
}
]
},
"riskScore": "LOW"
}'
Request Body Parameters (Company)
Attribute | Type | Required | Description |
---|---|---|---|
type | string | Yes | The type of customer. COMPANY indicates a business. |
company | object | Yes | Contains details of the company. |
company.name | string | Yes | The legal name of the company. |
company.description | string | No | Optional description or short bio of the company. |
company.entityType | string | Yes | Business entity type. Possible values: LIMITED_LIABILITY_COMPANY, PUBLICLY_LISTED_COMPANY, SOLE_PROPRIETOR, PARTNERSHIP, CORPORATION, TRUST, PRIVATE_FOUNDATION, CHARITY, NON_PROFIT_ORGANIZATION, PUBLIC_AGENCIES_OR_AUTHORITIES |
company.taxResidenceCountryCode | string | Yes | The country code for the company’s tax residence. |
company.registrationNumber | string | Yes | The official company registration or identifier. |
company.industryReference | string | Yes | Industry reference. Get list here |
company.monthlyExpectedVolumesReference | string | Yes | Monthly expected volumes reference. Get the list here . |
company.address | object | Yes | Address details of the company. |
company.address.addressLine1 | string | Yes | The first line of the company’s street address. |
company.address.addressLine2 | string | No | Optional second line. |
company.address.postalCode | string | Yes | The postal/ZIP code for the company’s address. |
company.address.city | string | Yes | The city for the company’s address. |
company.address.state | string | No | The state of the company’s address (U.S. only). |
company.address.countryCode | string | Yes | The country for the company’s address. |
company.associates | array | No | A list of individuals (UBOs, directors, signers) associated with the business. |
company.associates.person | object | Yes (per associate) | Personal details for the associate. |
company.associates.person.firstName | string | Yes | The given/first name. |
company.associates.person.lastName | string | Yes | The family/last name. |
company.associates.person.dateOfBirth | string | Yes | YYYY-MM-DD format. |
company.associates.person.address | object | Yes | Address details of the associate. |
company.associates.person.address.addressLine1 | string | Yes | The first line of the street address. |
company.associates.person.address.addressLine2 | string | No | Optional. |
company.associates.person.address.city | string | Yes | The city of the associate’s address. |
company.associates.person.address.postalCode | string | Yes | The postal/ZIP code. |
company.associates.person.address.countryCode | string | Yes | ISO-2 country code. |
company.associates.person.contactInfo | object | Yes | Optional contact info. |
company.associates.person.contactInfo.emailAddress | string | Yes | Email address. |
company.associates.person.taxIdentification | object | No | Optional tax ID details of the associate. |
company.associates.person.taxIdentification.number | string | No | E.g. SSN or TIN. |
company.associates.person.taxIdentification.taxResidenceCountryCode | string | No | ISO-2 code of the associate’s tax residence. |
company.associates.titles | array | Yes | Job title or position. Possible values BUSINESS_OWNER, ACCOUNT_REPRESENTATIVE, DIRECTOR |
signedAgreementSessionReference | string | Yes | Reference to an e-sign or terms acceptance session. |
riskScore | string | Yes | Overall risk rating of the Company, e.g. LOW , MEDIUM , HIGH |
Response
Response Code | Description |
---|---|
202 | Successful operation. |
400 | Bad request. |
Success Example:
{
"reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
"status": "PENDING"
}
Failure Example:
{
"code": "ACCOUNTS-2000",
"status": "BAD_REQUEST",
"message": "Invalid request",
"details": {
"errors": {
"industryReference": [
"Industry with reference: 56e65ebc-06fa-11ef-bbf8-02d3d923cf2b does not exist"
]
}
}
}
Add Documents to a Customer
Use these endpoints to attach documents to an existing customer—either at the company level or for a specific associate (beneficial owner, director, or signer). Each request can upload multiple documents simultaneously.
Important
- Reference the correct
customerReference
.- Use
customerPersonReference
when the document belongs to a specific associate. If omitted ornull
, the document is attached at the company level for business customers.- Files must be base64-encoded before sending.
Endpoints
Add Document(s)
Environment | Endpoint |
---|---|
Production | POST https://api.bvnk.com/platform/v1/customers/{customerReference}/documents |
Sandbox | POST https://api.sandbox.bvnk.com/platform/v1/customers/{customerReference}/documents |
Request Example
Example – uploading multiple documents for a customer (company and associate):
curl --location --request POST 'https://api.sandbox.bvnk.com/platform/v1/customers/123e4567-e89b-12d3-a456-426614174000/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="YourHawkID", ts="1678900000", nonce="abc123", mac="xyz789..."' \
--data-raw '[
{
"type": "COMPANY_DOC",
"subType": "INCORPORATION_CERT",
"name": "Company Structure.pdf",
"description": "Document optional description",
"countryCode": "GB",
"externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
"content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
},
{
"customerPersonReference": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab",
"type": "PASSPORT",
"subType": "FRONT_SIDE",
"name": "John Smith Passport.pdf",
"description": "Document optional description",
"countryCode": "GB",
"externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
"content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
}
]'
Path Parameter
Parameter | Type | Required | Description |
---|---|---|---|
customerReference | string | Yes | The unique identifier of the customer to whom the documents will be attached. Customer has to be in INFO_REQUIRED status (status after agreement consent) |
Request Body Parameters
Attribute | Type | Required | Description |
---|---|---|---|
customerPersonReference | string(36) | No | Links the document to a specific associate (e.g., beneficial owner). If omitted or null , the document is attached at the company level. |
type | string | Yes | The primary document type, e.g. PASSPORT , DRIVERS_LICENSE , COMPANY_DOC Full list of supported document types |
subType | string | No | Additional specification of the document type, e.g. FRONT_SIDE , BACK_SIDE if applicable.Full list of supported document subTypes |
name | string(128) | Yes | Optional human-readable filename, e.g. "John Smith Passport.pdf" . |
description | string(255) | No | Optional description for the provided document |
countryCode | string(2) | Yes | ISO 3166-1 alpha-2 country code associated with the document. |
externalReference | string(36) | Yes | The internal reference mapped to the document from your end. |
content | string | Yes | Base64-encoded file content. |
Response
Response Code | Description |
---|---|
202 | Request accepted and documents queued for upload. |
400 | Bad request (e.g., missing or invalid data). |
Success Example:
{
"reference": "d42e1c62-27b8-4b3b-b51e-eb10edeb1731",
"externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
"status": "INIT"
}
Failure Example:
{
"code": "DOCUMENTS-4000",
"status": "BAD_REQUEST",
"message": "Invalid document content",
"details": {
"errors": {
"content": [
"Document file content is not valid base64"
]
}
}
}
Additional Document APIs
Search Documents
GET /platform/v1/customers/documents
Optional Query Parameters:
customerReference
externalReference
name
types
subTypes
statuses
(e.g., INIT, PENDING, APPROVED, DECLINED)
Get Document Download URL
GET /platform/v1/customers/documents/{documentReference}/url
Returns a temporary URL for document download.
Delete Document
DELETE /platform/v1/customers/documents/{documentReference}
Returns 204 No Content
if successfully deleted.
Good to Know
-
Check Document Status
Retrieve the customer or associated person object to confirm document verification status. -
Retain Document References
Store thereference
returned in the success response for future queries or audits. -
Combine with KYC
Document verification may be required before the customer status changes fromPENDING
toVERIFIED
.
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 5 days ago