Retrieve customer details

• Embedded model

Customers API v2

The new customer onboarding flow is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.

With these endpoints, you can retrieve information about a specific customer within the system: key customer data, including their profile, associated wallets, and other relevant details. You can list all customers or acquire details of a specific one.

---

Retrieve all customers

To get a list of all your customers in the system, send the GET platform/v1/customers request.

In the response, you will receive the complete list of customers with the details:

{
    "content": [
        {
            "reference": "8a0e1da2-2af3-4b9e-a221-e74db4e01b06",
            "status": "VERIFIED",
            "type": "COMPANY",
            "model": "EMBEDDED",
            "name": "LB Ltd.",
            "description": "Embedded customer"
        },
        {
            "reference": "e38af699-5595-4ec4-a4d3-89b85e4fc906",
            "status": "PENDING",
            "type": "COMPANY",
            "model": "EMBEDDED",
            "name": "The Walt Disney company",
            "description": "Embedded customer two"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 2,
        "sort": {
            "empty": true,
            "sorted": false,
            "unsorted": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": false,
    "totalPages": 42,
    "totalElements": 83,
    "first": true,
    "size": 2,
    "number": 0,
    "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
    },
    "numberOfElements": 2,
    "empty": false
}

---

Retrieve customer's details

To get the detailed information of a specific customer, send the GET /platform/v1/customers/{customerReference} with the {customerReference} specified in the path.

In the successful response, you receive detailed information on this customer:

{
    "reference": "8a0e1da2-2af3-4b9e-a221-e74db4e01b06",
    "status": "PENDING",
    "type": "COMPANY",
    "company": {
        "name": "LB Ltd.",
        "description": "Embedded customer",
        "taxResidenceCountryCode": "US",
        "registrationNumber": "21-4532998",
        "address": {
            "addressLine1": "101 West Broadway",
            "addressLine2": "Suite 1975",
            "city": "San Diego",
            "postalCode": "92101",
            "countryCode": "US",
            "country": "United States"
        },
        "associates": [
            {
                "person": {
                    "reference": "911685b0-acaa-418d-bd91-ed80b96c62cf",
                    "firstName": "Sean",
                    "lastName": "Bond",
                    "dateOfBirth": "2001-01-31",
                    "address": {
                        "addressLine1": "101 West Broadway",
                        "addressLine2": "Suite 1975",
                        "city": "San Diego",
                        "postalCode": "92101",
                        "countryCode": "US",
                        "country": "United States"
                    }
                },
                "details": {
                    "birthCountryCode": "US",
                    "contactInfo": {
                        "emailAddress": "Sean.Bond@disney.com",
                        "phoneNumber": "+123456789"
                    },
                    "documentNumber": "123456789",
                    "documentInfo": {
                        "number": "123456789",
                        "type": "DRIVERS_LICENSE",
                        "issuingCountryCode": "US"
                    },
                    "taxIdentification": {
                        "number": "914764628",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "title": "CEO",
                "riskScore": "LOW",
                "controls": {
                    "hasOwnership": true,
                    "hasControl": true,
                    "isSigner": false
                },
                "verification": {
                    "url": "https://verify.com/2",
                    "status": "infoRequired"
                }
            },
            {
                "person": {
                    "reference": "c4cfa062-ea5f-49ca-96e0-8495e648520e",
                    "firstName": "Luke",
                    "lastName": "Dickens",
                    "dateOfBirth": "2001-01-31",
                    "address": {
                        "addressLine1": "101 West Broadway",
                        "addressLine2": "Suite 1975",
                        "city": "San Diego",
                        "postalCode": "92101",
                        "countryCode": "US",
                        "country": "United States"
                    }
                },
                "details": {
                    "birthCountryCode": "US",
                    "contactInfo": {
                        "emailAddress": "Luke.Dickens@disney.com",
                        "phoneNumber": "+123456789"
                    },
                    "documentNumber": "123456789",
                    "documentInfo": {
                        "number": "123456789",
                        "type": "DRIVERS_LICENSE",
                        "issuingCountryCode": "US"
                    },
                    "taxIdentification": {
                        "number": "914764628",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "title": "Representative",
                "riskScore": "LOW",
                "controls": {
                    "hasOwnership": false,
                    "hasControl": false,
                    "isSigner": true
                },
                "verification": {
                    "url": "https://verify.com/3",
                    "status": "infoRequired"
                }
            }
        ],
        "verification": {
            "url": "https://verify.com/1",
            "status": "infoRequired"
        }
    },
    "riskScore": "LOW"
}

---

List required information

When receiving the response with the status INFO_REQUIRED from GET /platform/v1/customers/{customerReference}, you can request the complete list of missing documents required to complete the customer onboarding. For that, send the GET /platform/v1/customers/{customerReference}/info-required request with the ID of your customer in the path.

The customer can be in the following statuses:

• INFO_REQUIRED: Additional documents or information are required to complete the customer onboarding.
• REJECTED: The customer application was rejected and the onboarding cannot proceed.
• VERIFIED: The customer application is approved and the onboarding is complete.

In this case, a similar corresponding response is shown:

{
    "status": "VERIFIED"
}

For the status INFO_REQUIRED, you receive the following responses, depending on the customer type:

Individual

In the response, you receive the list of documents to provide.

{
    "status": "INFO_REQUIRED",
    "infoRequired": {
        "questionnaires": [],
        "documents": [
            {
                "docSetType": "IDENTITY",
                "types": [
                    "PASSPORT",
                    "DRIVERS",
                    "ID_CARD",
                    "RESIDENCE_PERMIT"
                ]
            },
            {
                "docSetType": "SELFIE",
                "types": [
                    "SELFIE"
                ]
            }
        ],
        "data": []
    },
    "verificationFailure": {
        "reasons": [
            {
                "failureCode": "PROBLEMATIC_APPLICANT_DATA:fullName",
                "description": "Name mismatch detected"
            }
        ]
    }
}

If the verification status is INFO_REQUIRED due to a failure, the verificationFailure object is populated with a list of specific reasons. Each reason includes a machine-readable failureCode for programmatic handling and a human-readable description explaining the mismatch or error.

According to the earlier example, you must upload the following documents for your customer:

• Any IDENTITY, for example, a passport or a residence permit.
• SELFIE

Company

In the response, you receive the list of documents to provide.

{
    "status": "INFO_REQUIRED",
    "infoRequired": {
        "questionnaires": [
            "QuestionnaireFull"
        ]
    }
}

For example, the earlier response shows that you need to provide a questionnaire. To upload it, follow the Gather Compliance Data for Onboarding guides.

After you pass the "questionnaire" stage, you could receive another response requiring you to provide the associates information.

{
    "status": "INFO_REQUIRED",
    "infoRequired": {
        "associates": [
            {
                "roles": [
                    "BUSINESS_OWNER",
                    "DIRECTOR",
                    "ACCOUNT_REPRESENTATIVE"
                ]
            }
        ]
    }
}

After you add the information, you get the following response:

{
  "status": "INFO_REQUIRED",
  "infoRequired": {
      "questionnaires": [
          "additionalCompanyDat"
      ],
      "associates": [
          {
              "customerPersonReference": "6599f942-dd82-4c1c-a9f1-d5e0e40a4368",
              "associateName": "Gabriel Syme",
              "roles": [
                  "BUSINESS_OWNER",
                  "DIRECTOR",
                  "ACCOUNT_REPRESENTATIVE"
              ],
              "documents": [
                  {
                      "docSetType": "IDENTITY",
                      "types": [
                          "DRIVERS",
                          "ID_CARD",
                          "RESIDENCE_PERMIT",
                          "PASSPORT"
                      ]
                  },
                  {
                      "docSetType": "SELFIE",
                      "types": [
                          "SELFIE"
                      ]
                  },
                  {
                      "docSetType": "PROOF_OF_RESIDENCE",
                      "types": [
                          "UTILITY_BILL"
                      ]
                  }
              ],
              "data": [
                  "dateOfBirth",
                  "details.nationality",
                  "details.contactInfo.emailAddress",
                  "details.taxIdentification.number",
                  "details.taxIdentification.taxResidenceCountry"
              ]
          }
      ]
  }
}

Here, the systems requests additional data and the complete set of documents to be uploaded. To provide it, follow the Add Documents to customers guides to upload or re-upload the documents. If the documents still can't be accepted after re-upload, you can send the link from verification.url to your customers so that they can provide the correct materials.

"verification": {
    "status": "infoRequired",
    "url": "https://VERIFICATION_WEBSITE.com/C6PqOEXyQRFtSrDz"
}

Let's say, you've provided the needed information and documents, but the selfie was of poor quality. In this case, you receive the following response:

{
  "status": "INFO_REQUIRED",
  "infoRequired": {
      "questionnaires": [
          "additionalCompanyDat"
      ],
      "associates": [
          {
              "customerPersonReference": "6599f942-dd82-4c1c-a9f1-d5e0e40a4368",
              "associateName": "Gabriel Syme",
              "roles": [
                  "BUSINESS_OWNER",
                  "DIRECTOR",
                  "ACCOUNT_REPRESENTATIVE"
              ],
              "documents": [
                  {
                      "docSetType": "SELFIE",
                      "types": [
                          "SELFIE"
                      ]
                  }
              ]
          }
      ]
  }
}

After all the requirements are satisfied, the response may look like as follows:

{
    "status": "INFO_REQUIRED",
    "infoRequired": {

    }
}

Retrieve customer details by page and size

To get the detailed information of a specific customer, send the GET /platform/v1/customers?page={page}&size={size} with the {page} and {size} specified in the path.

curl --location 'https://api.sandbox.bvnk.com/platform/v1/customers?page=0&size=20' \
--header 'Authorization: Hawk id="vbfc61D890wg6LAAVbkR11qP9O6cXeMNmKWgcUNZaOHPiQeebp9cl6h02tWv84R8", ts="1728656129", nonce="nt0eD9", mac="gv77Nu/nVWEQo8sfp/leXrC8xVs6UlOG+AoxZlyltJw="'

In the successful response, you will receive the details of the customers:

{
    "content": [
        {
            "reference": "61461ad5-0599-4a4a-8e4e-c2575605f5bb",
            "status": "PENDING",
            "type": "COMPANY",
            "name": "UK Ltd Version 2.0",
            "description": "Number 1 customer, be super nice."
        },
        {
            "reference": "60bf3fed-7e76-4cc8-9c1f-e0f19878e0c8",
            "status": "PENDING",
            "type": "COMPANY",
            "name": "UK Ltd Version 2.0",
            "description": "Number 1 customer, be super nice."
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 2,
        "sort": {
            "empty": true,
            "sorted": false,
            "unsorted": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": false,
    "totalPages": 5,
    "totalElements": 9,
    "first": true,
    "size": 2,
    "number": 0,
    "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
    },
    "numberOfElements": 2,
    "empty": false
}

Attribute	Type	Description
pageNumber	Integer	Current page number (e.g., 0 for the first page).
pageSize	Integer	Number of records per page (e.g., 2).
sort.empty	Boolean	Whether the sort criteria is empty (true means no sorting).
sort.sorted	Boolean	Whether the results are sorted (false means no sorting).
sort.unsorted	Boolean	Whether the results are unsorted (true means not sorted).
offset	Integer	Offset of the first record (e.g., 0, meaning no offset).
paged	Boolean	Whether the results are paginated (true).
unpaged	Boolean	Whether the results are not paginated (false).
last	Boolean	Whether this is the last page of results (false means more pages exist).
totalPages	Integer	Total number of pages (e.g., 10 pages).
totalElements	Integer	Total number of elements across all pages (e.g., 20 elements).
first	Boolean	Whether this is the first page (true).
size	Integer	Number of elements per page (e.g., 2).
number	Integer	The current page number (e.g., 0 for the first page).
sort.empty	Boolean	Whether the sort criteria is empty (true).
sort.sorted	Boolean	Whether the results are sorted (false).
sort.unsorted	Boolean	Whether the results are unsorted (true).
numberOfElements	Integer	Number of elements in the current page (e.g., 2).
empty	Boolean	Whether the page is empty (false means there are elements).