Retrieve Customer Details

This endpoint allows you to retrieve the information about a specific customer within the system. By using this endpoint, you can access key customer data, including their profile, associated virtual IBANs, and other relevant details. You can either list all customers or else choose to list only a specific one. Examples below:


🚧

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.

📘

Note

This endpoint includes pagination.

  • page: page number which starts from 0
  • size: page size which limits the number of returned customers in the response

Retrieving all customer details

Request

EnvironmentEndpoint
ProductionGET https://api.bvnk.com/platform/v1/customers
SandboxGET https://api.sandbox.bvnk.com/platform/v1/customers
curl --location 'https://api.sandbox.bvnk.com/platform/v1/customers' \
--header 'Authorization: Hawk id="vOjKT0txxpp6TMQP6QTQziyBjAiVnMGNH3dbFa0SGhK7OFsMD6lWFPaN8TXCqkXk", ts="1724508332", nonce="O7KMY1", mac="yBxrGq5pKFcAe0taEYf/OI3rQwJDHHF3S6rZB9WVjCw="'

Response

{
    "content": [  
         {
            "reference": "6f6c6bee-58e7-4bc3-ae43-b7f84cd6cc93",
            "status": "PENDING",
            "type": "COMPANY",
            "name": "Umbrella Ltd",
            "description": "This is the company description"
        },
         {
           "reference": "0a184641-30e2-4414-871f-3db1c683900e",
      		 "status": "VERIFIED",
           "type": "COMPANY",
           "name": "Fast Cars LTD",
           "description": "Description for Fast Cars LTD "
         },
        {
            "reference": "71a4bffc-8f23-4601-9f36-194c041c99eb",
            "status": "PENDING",
            "type": "COMPANY",
            "name": "Acme",
            "description": "This is the company description"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "empty": true,
            "sorted": false,
            "unsorted": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": true,
    "totalPages": 1,
    "totalElements": 20,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
    },
    "numberOfElements": 20,
    "empty": false
}

Retrieving details for a specific customer

Request

EnvironmentEndpoint
ProductionGET https://api.bvnk.com/platform/v1/customers/{customerReference}
SandboxGET https://api.sandbox.bvnk.com/platform/v1/customers/{customerReference}
curl --location 'https://api.sandbox.bvnk.com/platform/v1/customers/a7e21c62-27b8-4b3b-b51e-eb10edeb1731' \
--header 'Authorization: Hawk id="vbfc61D890wg6LAAVbkR11qP9O6cXeMNmKWgcUNZaOHPiQeebp9cl6h02tWv84R8", ts="1728655974", nonce="daA3d2", mac="57bCwwkcIObYV8pIGUJNUg/F66g24wAGr4p4VcbwyFc="'

Response

Response CodeStatus
200Successful operation.
404The specified resource was not found.
{
    "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
    "status": "VERIFIED",
    "type": "COMPANY",
    "company": {
        "name": "Fast Food Ltd",
        "description": "Description for Fast Food Ltd",
        "taxResidenceCountryCode": "GB",
        "registrationNumber": "123456",
        "industry": {
            "reference": "30ea15fc-06d8-11ef-b6e1-027612b7f6b5",
            "name": "Food/Beverages"
        },
        "monthlyExpectedVolumes": {
            "reference": "ef779c41-547e-11ef-8b9c-027612b7f6b5",
            "name": "0 - 500 000.00 EUR",
            "min": 0,
            "max": 500000
        },
        "address": {
            "addressLine1": "123 Main Street",
            "addressLine2": "Apartment 456",
            "city": "London",
            "postalCode": "NW1 4NP",
            "countryCode": "GB",
            "country": "United Kingdom"
        },
        "representative": {
            "reference": "270e9689-2a1b-48f4-819d-5baccb431cdb",
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "2001-12-31",
            "address": {
                "addressLine1": "1, Oxford Street",
                "addressLine2": "Apartment 9",
                "city": "London",
                "postalCode": "NW1 4NP",
                "countryCode": "GB",
                "country": "United Kingdom"
            }
        }
    }
}

Attribute

Type

Description

reference

String

A unique identifier for the customer request.

status

String

Status of the customer (e.g., "VERIFIED"). Possible statuses could include PENDING, VERIFIED, REJECTED.

type

String

The type of customer.

company

Object

Details about the company.

company.name

String

Name of the company.

company.description

String

Description of the company.

company.taxResidenceCountryCode

String

Country code for tax residence.

company.registrationNumber

String

Registration number of the company.

company.industry

Object

The industry details of the company.

company.industry.
reference

String

Industry reference ID.

company.industry.
name

String

Name of the industry.

company.industry.
children

Array

Subcategories or children industries (if any).

company.monthlyExpectedVolumes

Object

The monthly expected volumes of the company.

company.monthlyExpectedVolumes.
reference

String

Volume reference ID.

company.monthlyExpectedVolumes.
name

String

Expected monthly volume description.

company.monthlyExpectedVolumes.
min

Number

Minimum expected volume.

company.monthlyExpectedVolumes.
max

Number

Maximum expected volume.

company.address

Object

The address of the company.

company.address.
addressLine1

String

Primary address line.

company.address.
addressLine2

String

Secondary address line.

company.address.
postalCode

String

Postal code.

company.address.
city

String

City.

company.address.
countryCode

String

Country code.

company.address.
country

String

Full country name.

company.representative

Object

The representative of the company.

company.representative.
firstName

String

First name of the representative.

company.representative.
lastName

String

Last name of the representative.

company.representative.
dateOfBirth

String

Date of birth of the representative.

company.representative.
address

Object

The representative address of the company.

company.representative.address.
addressLine1

String

Primary address line of the representative.

company.representative.address.
addressLine2

String

Secondary address line of the representative.

company.representative.address.
postalCode

String

Postal code of the representative.

company.representative.address.
city

String

City of the representative.

company.representative.address.
countryCode

String

Country code of the representative.

company.representative.address.
country

String

Full country name of the representative.


Retrieving details by specifying page and size

Request

EnvironmentEndpoint
ProductionGET https://api.bvnk.com/platform/v1/customers?page={page}&size={size}
SandboxGET https://api.sandbox.bvnk.com/platform/v1/customers?page={page}&size={size}\
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="'

Response

{
    "content": [
        {
            "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
            "status": "VERIFIED",
            "type": "COMPANY",
            "name": "Fast Food Ltd",
            "description": "Description for Fast Food Ltd"
        },
        {
            "reference": "e34cc6a3-250a-4fff-be58-2894b8d6ca3c",
            "status": "VERIFIED",
            "type": "COMPANY",
            "name": "Fast Cars Ltd",
            "description": "Description for Fast Cars Ltd"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "empty": true,
            "unsorted": true,
            "sorted": false
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": true,
    "totalPages": 1,
    "totalElements": 2,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
        "empty": true,
        "unsorted": true,
        "sorted": false
    },
    "numberOfElements": 2,
    "empty": false
}

Pageable details:

AttributeTypeDescription
pageNumberIntegerCurrent page number (e.g., 0 for the first page).
pageSizeIntegerNumber of records per page (e.g., 2).
sort.emptyBooleanWhether the sort criteria is empty (true means no sorting).
sort.sortedBooleanWhether the results are sorted (false means no sorting).
sort.unsortedBooleanWhether the results are unsorted (true means not sorted).
offsetIntegerOffset of the first record (e.g., 0, meaning no offset).
pagedBooleanWhether the results are paginated (true).
unpagedBooleanWhether the results are not paginated (false).
lastBooleanWhether this is the last page of results (false means more pages exist).
totalPagesIntegerTotal number of pages (e.g., 10 pages).
totalElementsIntegerTotal number of elements across all pages (e.g., 20 elements).
firstBooleanWhether this is the first page (true).
sizeIntegerNumber of elements per page (e.g., 2).
numberIntegerThe current page number (e.g., 0 for the first page).
sort.emptyBooleanWhether the sort criteria is empty (true).
sort.sortedBooleanWhether the results are sorted (false).
sort.unsortedBooleanWhether the results are unsorted (true).
numberOfElementsIntegerNumber of elements in the current page (e.g., 2).
emptyBooleanWhether the page is empty (false means there are elements).