Sandbox LoginProduction LoginStatus Page
Quickstart Guides
Start typing to search…

Creating a Company Customer

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

🚧

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.

📘

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/platform/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

Attribute

Type

Required

Description

type

String

Yes

The type of customers. Currently COMPANY only is allowed, which indicates its a business customer.

company

Object

Yes

Contains the company details for the customer.

company.name

String

Yes

The name of the customer.

company.description

String

No

Optional field for the description of the customer

company.monthlyExpectedVolumesReference

String

Yes

Monthly expected volumes reference. Get the list here.

company.industryReference

String

Yes

Industry reference. Get the list here.

company.taxResidenceCountryCode

String

Yes

The company tax residence country code for the customer.

company.registrationNumber

String

Yes

The company registration number for the customer.

company.address

Object

Yes

Contains company address details.

company.address.
addressLine1

String

Yes

The company address for the customer.

company.address.
addressLine2

String

No

Optional field to add another address line.

company.address.
city

String

Yes

The company address city for the customer.

company.address.
postalCode

String

Yes

The company address postal code for the customer.

company.address.
countryCode

String

Yes

The company address country code for the customer.

company.representative

Object

Yes

Contains information about the company representative for the customer.

company.representative.
firstName

String

Yes

The company representative first name.

company.representative.
lastName

String

Yes

The company representative last name.

company.representative.
dateOfBirth

String

Yes

The company representative date of birth.

company.representative.address

Object

Yes

Validation 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"
}

Attribute

Type

Description

reference

string

A unique identifier for the customer.

status

string

The 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 2 days ago