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 and individuals based in the US, 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.

  1. 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.
  2. 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.
  3. Pending
    • Once verification flow is submitted, BVNK performs compliance checks.
    • During this time, you can monitor the EPC’s status in the portal.
  4. Verified
    • The EPC has successfully passed the compliance review.
    • Wallets can now be created and used.
  5. 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.


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”).

Endpoints

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

Request

Example – business customer creation with associates:

{
    "type": "COMPANY",
    "company": {
        "name": "The Walt company",
        "description": "Entertainment Business",
        "entityType": "CORPORATION",
        "taxResidenceCountryCode": "US",
        "registrationNumber": "123456789",
        "industryReference": "30ea5818-06d8-11ef-b6e1-027612b7f6b5",
        "monthlyExpectedVolumesReference": "ef779c41-547e-11ef-8b9c-027612b7f6b5",
        "address": {
            "addressLine1": "Waterloo Bridge 13",
            "city": "London",
            "postalCode": "12345",
            "countryCode": "US"
        },
        "associates": [
            {
                "person": {
                    "firstName": "Donald",
                    "lastName": "Duck",
                    "dateOfBirth": "1908-11-29",
                    "nationality": "US",
                    "address": {
                        "addressLine1": "1313 Webfoot Street",
                        "city": "Duckburg",
                        "postalCode": "12345",
                        "stateCode": "CA",
                        "countryCode": "US"
                    },
                    "contactInfo": {
                        "emailAddress": "donald.duck@disney.com"
                    },
                    "taxIdentification": {
                        "number": "384-37-3429",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "titles": [
                    "BUSINESS_OWNER",
                    "DIRECTOR"
                ]
            }
        ]
    },
    "riskScore": "LOW",
    "signedAgreementSessionReference": "f6541903-a0b4-4da3-99eb-f36608a6e857"
}

Request Body Parameters (Company)

AttributeTypeRequiredDescription
typestringYesThe type of customer. COMPANY indicates a business.
companyobjectYesContains details of the company.
company.namestringYesThe legal name of the company.
company.descriptionstringNoOptional description or short bio of the company.
company.entityTypestringYesBusiness 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.taxResidenceCountryCodestringYesThe country code for the company’s tax residence.
company.registrationNumberstringYesThe official company registration or identifier.
company.industryReferencestringYesIndustry reference. Get list here
company.monthlyExpectedVolumesReferencestringYesMonthly expected volumes reference. Get the list here .
company.addressobjectYesAddress details of the company.
company.address.addressLine1stringYesThe first line of the company’s street address.
company.address.addressLine2stringNoOptional second line.
company.address.postalCodestringYesThe postal/ZIP code for the company’s address.
company.address.citystringYesThe city for the company’s address.
company.address.stateCodestringNoThe state of the company’s address (U.S. only).
company.address.countryCodestringYesThe country for the company’s address.
company.associatesarrayNoA list of individuals (UBOs, directors, signers) associated with the business.
company.associates.personobjectYes (per associate)Personal details for the associate.
company.associates.person.firstNamestringYesThe given/first name.
company.associates.person.lastNamestringYesThe family/last name.
company.associates.person.dateOfBirthstringYesYYYY-MM-DD format.
company.associates.person.nationalitystringYesISO-2 country code.
company.associates.person.addressobjectYesAddress details of the associate.
company.associates.person.address.addressLine1stringYesThe first line of the street address.
company.associates.person.address.addressLine2stringNoOptional second line
company.associates.person.address.citystringYesThe city of the associate’s address.
company.associates.person.address.postalCodestringYesThe postal/ZIP code.
company.associates.person.address.countryCodestringYesISO-2 country code.
company.associates.person.contactInfoobjectYesOptional contact info.
company.associates.person.contactInfo.emailAddressstringYesEmail address.
company.associates.person.taxIdentificationobjectYesTax Identification details
company.associates.person.taxIdentification.numberstringYesSSN/ITIN for US, Tax number for Rest of the world
company.associates.person.taxIdentification.taxResidenceCountryCodestringYesISO-2 code of the associate’s tax residence.
company.associates.titlesarrayYesJob title or position. Possible values BUSINESS_OWNER, ACCOUNT_REPRESENTATIVE, DIRECTOR
signedAgreementSessionReferencestringYesReference to an e-sign or terms acceptance session.
riskScorestringYesOverall risk rating of the Company, e.g. LOW, MEDIUM, HIGH

Response

Response CodeDescription
202Successful operation.
400Bad request.

Success Example:

{
  "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
  "status": "INFO_REQUIRED"
}

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 Company 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 customerPersonReferenceis omitted or null, the document is attached at the company level for business customers.**
  • Files must be base64-encoded before sending.

Endpoints

Add Document(s)

EnvironmentEndpoint
ProductionPOST https://api.bvnk.com/platform/v1/customers/{customerReference}/documents
SandboxPOST https://api.sandbox.bvnk.com/platform/v1/customers/{customerReference}/documents

Request Example

Example – uploading multiple documents for a customer (company and associate):

[
    {
        "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

ParameterTypeRequiredDescription
customerReferencestringYesThe unique identifier of the customer to whom the documents will be attached. Customer has to be in INFO_REQUIREDstatus (status after agreement consent)

Request Body Parameters

AttributeTypeRequiredDescription
customerPersonReferencestring(36)NoLinks the document to a specific associate (e.g., beneficial owner). If omitted or null, the document is attached at the company level.
typestringYesThe document type e.g COMPANY_DOC
Full list of supported COMPANY document type

When uploading documents for an associate (e.g. ) refer to the following list for supported document type(s)
Full list of supported ASSOCIATE (Individual) document types
subTypestringNoAdditional specification of the document type, e.g. FRONT_SIDE, BACK_SIDE if applicable.
Full list of supported document subType for COMPANY documents

When uploading documents for an associate (e.g. PASSPORT) refer to the following list for supported document subType(s)
Full list of supported ASSOCIATE (Individual) document subType
namestring(128)YesOptional human-readable filename, e.g. "John Smith Passport.pdf".
descriptionstring(255)NoOptional description for the provided document
countryCodestring(2)YesISO 3166-1 alpha-2 country code associated with the document.
externalReferencestring(36)YesThe internal reference mapped to the document from your end.
contentstringYesBase64-encoded file content.

Response

Response CodeDescription
202Request accepted and documents queued for upload.
400Bad 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

  1. Check Document Status
    Retrieve the customer or associated person object to confirm document verification status.

  2. Retain Document References
    Store the reference returned in the success response for future queries or audits.

  3. Combine with KYC
    Document verification may be required before the customer status changes from PENDING to VERIFIED.

Complete Onboarding

Once you have uploaded all required documentation for an Embedded Partner Customer (EPC), you must confirm the completion of the onboarding process by calling the following endpoint:

Endpoint

EnvironmentMethodURL
ProductionPOSThttps://api.bvnk.com/platform/v1/customers/{reference}/complete-onboarding
SandboxPOSThttps://api.sandbox.bvnk.com/platform/v1/customers/{reference}/complete-onboarding

Path Parameters

ParameterTypeRequiredDescription
referencestringYesThe unique reference identifier for the Embedded Partner Customer (EPC) provided during customer creation.

What Happens Next?

When you successfully call this endpoint:

  • BVNK will initiate final compliance and verification checks.
  • In the sandbox environment, EPC verification is automatically approved.
  • In production, if the EPC meets all compliance requirements, the status will update to VERIFIED. If there are outstanding requirements or issues, the status will move to INFO_REQUIRED or REJECTED, prompting manual review or further actions.

Monitoring Status

You can monitor the EPC's verification status via:

  • API: Retrieve current status using GET /platform/v1/customers/{reference}
  • Portal: Track progress and statuses directly through the BVNK Portal
  • Webhooks: Set up webhooks to receive automated updates on status changes.