Sandbox LoginProduction LoginStatus Page
Quickstart Guides

Creating a Company Customer

Suggest Edits

This endpoint enables you to easily create an individual entity customer within the system.

🚧

BETA endpoint

Please note that this endpoint is currently in beta, and it may undergo changes as we continue to improve and refine the functionality.

📘

Prerequisites

You will need to collect information about the customer before proceeding with the request to create one. Apart from the typical information you will also need to include the industry reference number and the expected monthly volumes.

📘

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.

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

Create request

curl --location 'https://api.sandbox.bvnk.com/api/v1/customers' \
--header 'X-Idempotency-Key: 0b3ed172-e24f-43f5-a901-4f7b6d138ebe' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="vbfc61D890wg6LAAVbkR11qP9O6cXeMNmKWgcUNZaOHPiQeebp9cl6h02tWv84R8", ts="1728655954", nonce="MdPBLt", mac="jGEwZvz7rVO3lM3Ose8Ww1PtgnsHBe7eFph3Nzj5H6Y="' \
--data '{
    "type": "COMPANY",
    "company": {
        "name": "Fast Food Ltd",
        "description": "Description for Fast Food Ltd",
        "taxResidenceCountryCode": "GB",
        "registrationNumber": "123456",
        "industryReference": "30ea15fc-06d8-11ef-b6e1-027612b7f6b5",
        "monthlyExpectedVolumesReference": "ef779c41-547e-11ef-8b9c-027612b7f6b5",
        "address": {
            "addressLine1": "123 Main Street",
            "addressLine2": "Apartment 456",
            "postalCode": "NW1 4NP",
            "city": "London",
            "countryCode": "GB"
        },
        "representative": {
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "2001-12-31",
            "address": {
                "addressLine1": "1, Oxford Street",
                "addressLine2": "Apartment 9",
                "postalCode": "NW1 4NP",
                "city": "London",
                "countryCode": "GB"
            }
        }
    }
}'

The details supplied to the create a Company entity customer

AttributeTypeRequiredDescription
typeStringYesThe type of customers. Currently COMPANY only is allowed, which indicates its a business customer.
companyObjectYesContains the company details for the customer.
company.nameStringYesThe name of the customer.
company.descriptionStringNoOptional field for the description of the customer
company.monthlyExpectedVolumesReferenceStringYesMonthly expected volumes reference. Get the list here.
company.industryReferenceStringYesIndustry reference. Get the list here.
company.taxResidenceCountryCodeStringYesThe company tax residence country code for the customer.
company.registrationNumberStringYesThe company registration number for the customer.
company.addressObjectYesContains company address details.
company.address.
addressLine1		StringYesThe company address for the customer.
company.address.
addressLine2		StringNoOptional field to add another address line.
company.address.
city		StringYesThe company address city for the customer.
company.address.
postalCode		StringYesThe company address postal code for the customer.
company.address.
countryCode		StringYesThe company address country code for the customer.
company.representativeObjectYesContains information about the company representative for the customer.
company.representative.
firstName		StringYesThe company representative first name.
company.representative.
lastName		StringYesThe company representative last name.
company.representative.
dateOfBirth		StringYesThe company representative date of birth.
company.representative.addressObjectYesValidation is similar to the above company.address. This object expects details for the company representative address.

Response

Response CodeDescription
202Successful operation.
400Bad request.
{
    "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
    "status": "PENDING"
}
AttributeTypeDescription
referencestringA unique identifier for the customer.
statusstringThe current status of the customer.
Possible values include:

- PENDING - customer is pending verification,
- VERIFIED - customer has been verified,
- REJECTED - customer has been rejected during verification.
{
    "code": "ACCOUNTS-2000",
    "status": "BAD_REQUEST",
    "message": "Invalid request",
    "details": {
        "documentLink": null,
        "errors": {
            "monthlyExpectedVolumesReference": [
                "Monthly expected volumes with reference: a4318a0d-5316-11ef-9887-0289b1b0d83d does not exist"
            ],
            "industryReference": [
                "Industry with reference: 56e65ebc-06fa-11ef-bbf8-02d3d923cf2b does not exist"
            ]
        }
    }
}

Updated 15 days ago