Create a Customer via API

Once a customer is created, we initiate verification. You can then retrieve the customer object or listen to webhooks 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.

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.

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

Prerequisites

Collect and validate customer data (IDs, address proofs, and so on) before creating the customer. This is crucial for a smooth KYC/KYB flow.
Remember to obtain the verified reference from the signed agreement session and include it in the request payload as the signedAgreementSessionReference field. This ensures the agreements are properly linked and recognized in your new customer creation and onboarding.

Create customer

Select a type of customer you want to create:

Use this endpoint to create a business or company EPC. You can associate multiple beneficial owners, controlling persons, and signers (often referred to collectively as “associates”).

To create a business EPC, send the POST /customers request with the following request body:

{
    "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": "[email protected]"
                    },
                    "taxIdentification": {
                        "number": "384-37-3429",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "titles": [
                    "BUSINESS_OWNER",
                    "DIRECTOR"
                ]
            }
        ]
    },
    "riskScore": "LOW",
    "signedAgreementSessionReference": "f6541903-a0b4-4da3-99eb-f36608a6e857"
}

Request Body Parameters

Attribute	Required	Description
type	Yes	The type of customer. `COMPANY` indicates a business.
company	Yes	Contains details of the company.
company.name	Yes	The legal name of the company.
company.description	No	Optional description or short bio of the company.
company.entityType	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	Yes	The country code for the company’s tax residence.
company.registrationNumber	Yes	The official company registration or identifier.
company.industryReference	Yes	Industry reference. Get list here
company.monthlyExpectedVolumesReference	Yes	Monthly expected volumes reference. Get the list here .
company.address	Yes	Address details of the company.
company.address.addressLine1	Yes	The first line of the company’s street address.
company.address.addressLine2	No	Optional second line.
company.address.postalCode	Yes	The postal/ZIP code for the company’s address.
company.address.city	Yes	The city for the company’s address.
company.address.stateCode	No	The state of the company’s address (U.S. only).
company.address.countryCode	Yes	The country for the company’s address.
company.associates	No	A list of individuals (UBOs, directors, signers) associated with the business.
company.associates.person	Yes (per associate)	Personal details for the associate.
company.associates.person.firstName	Yes	The given/first name.
company.associates.person.lastName	Yes	The family/last name.
company.associates.person.dateOfBirth	Yes	`YYYY-MM-DD` format.
company.associates.person.nationality	Yes	ISO-2 country code.
company.associates.person.address	Yes	Address details of the associate.
company.associates.person.address.addressLine1	Yes	The first line of the street address.
company.associates.person.address.addressLine2	No	Optional second line
company.associates.person.address.city	Yes	The city of the associate’s address.
company.associates.person.address.postalCode	Yes	The postal/ZIP code.
company.associates.person.address.countryCode	Yes	ISO-2 country code.
company.associates.person.contactInfo	Yes	Optional contact info.
company.associates.person.contactInfo.emailAddress	Yes	Email address.
company.associates.person.taxIdentification	Yes	Tax Identification details
company.associates.person.taxIdentification.number	Yes	SSN/ITIN for US, Tax number for Rest of the world
company.associates.person.taxIdentification.taxResidenceCountryCode	Yes	ISO-2 code of the associate’s tax residence.
company.associates.titles	Yes	Job title or position. Possible values BUSINESS_OWNER, ACCOUNT_REPRESENTATIVE, DIRECTOR
signedAgreementSessionReference	Yes	Reference to an e-sign or terms acceptance session.
riskScore	Yes	Overall risk rating of the Company, e.g. `LOW`, `MEDIUM`, `HIGH`

In the successful response you receive a unique customer reference CustomerReference for tracking the verification status.

{
  "reference": "b0ef182b-202d-4365-b69d-98dcb225fd62",
  "status": "INFO_REQUIRED",
  "infoRequired": {
      "questionnaireCodes": ["financialServicesQuestionnaireFull"]
  }
}

{
  "code": "ACCOUNTS-2000",
  "status": "BAD_REQUEST",
  "message": "Invalid request",
  "details": {
    "errors": {
      "industryReference": [
        "Industry with reference: 56e65ebc-06fa-11ef-bbf8-02d3d923cf2b does not exist"
      ]
    }
  }
}

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. Note that in this case the code for a related questionnaire is sent. For more information, see Retrieve Compliance Data • `PENDING` – pending customer verification • `VERIFIED` – customer has been verified • `REJECTED` – verification has been unsuccessful.

📘Idempotency supported endpoint

Prerequisites

Create customer

Request Body Parameters

📘
Idempotency supported endpoint