Customers

Create customer

Changed on Nov 6, 2026

:::warning Before calling this endpoint, make sure you are not onboarding customers from restricted jurisdictions. For more information, see BVNK Acceptable Use Policy. :::

:::info 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. :::

Creates an Embedded Partner Customer account. The customer can be 'Individual' or 'Company'.

:::info Tax self-certification You can send the customer's tax self-certification in this request. The tax fields are optional for now. BVNK will give partners notice before they become mandatory.

Tax fields are not accepted for the Nested model. :::

post/platform/v1/customers

Request

Base URL
https://api.sandbox.bvnk.com
Auth
API key in header Authorization
TypeScript
https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/platform/v1/customers/post.ts
A function with typed inputs. Its response is checked against the schema.

Headers

X-Idempotency-Keystring uuid required

Example:1e74002e-74a1-48fd-b707-147c3187a3e1

Unique request identifier (any string, preferably in UUID format).

Request body

Example request

{
  "type": "company",
  "company": {
    "name": "UK Ltd Version 2.0",
    "description": "Number 1 customer, be super nice.",
    "taxResidenceCountryCode": "DE",
    "taxNumber": "12-34567890",
    "taxResidences": [
      {
        "country": "ES",
        "tin": "48291734Z",
        "noTinReason": "UNABLE_TO_OBTAIN",
        "noTinExplanation": "Moved to Portugal in September 2026. The NIF application is still being processed."
      }
    ],
    "countryOfIncorporation": "ES",
    "crsClassification": "PASSIVE_NFE",
    "carfClassification": "OTHER_ENTITY",
    "taxDeclaration": {
      "acceptedAt": "2026-10-20T09:15:00Z",
      "signatory": {
        "fullName": "Lucía Fernández",
        "capacity": "DIRECTOR"
      }
    },
    "registrationNumber": "1849203",
    "industryReference": "0a184641-30e2-4414-871f-3db1c683900e",
    "monthlyExpectedVolumesReference": "0a184641-30e2-4414-871f-3db1c683900e",
    "sourceOfFunds": "COMMERCIAL_ACTIVITIES",
    "intendedUseOfAccount": "CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS",
    "address": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Apartment 456",
      "postalCode": "NW1 4NP",
      "city": "London",
      "countryCode": "GB",
      "country": "Great Britain",
      "stateCode": "AL"
    },
    "cdd": {
      "pepStatus": "NOT_PEP",
      "intendedUseOfAccount": "PAYROLL",
      "expectedMonthlyVolume": {
        "amount": "50000.00",
        "currency": "EUR"
      }
    },
    "operationalAddress": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Apartment 456",
      "postalCode": "NW1 4NP",
      "city": "London",
      "countryCode": "GB",
      "country": "Great Britain",
      "stateCode": "AL"
    },
    "incorporationDate": "2001-12-31",
    "website": "https://www.example.com",
    "associates": [
      {
        "person": {
          "firstName": "John",
          "lastName": "Hurt",
          "dateOfBirth": "2001-12-31",
          "birthCountryCode": "HK",
          "placeOfBirth": "Hong Kong",
          "nationality": "US",
          "address": {
            "addressLine1": "123 Main Street",
            "addressLine2": "Apartment 456",
            "postalCode": "NW1 4NP",
            "city": "London",
            "countryCode": "GB",
            "country": "Great Britain",
            "stateCode": "AL"
          },
          "contactInfo": {
            "emailAddress": "wsimmons@example.com",
            "phoneNumber": "+1234567890"
          },
          "taxIdentification": {
            "number": "123-45-6789",
            "taxResidenceCountryCode": "US"
          },
          "estimatedYearlyIncome": "INCOME_0_TO_50K",
          "reliance": {
            "identityDocumentMetadata": {
              "type": "PASSPORT",
              "number": "AB1234567",
              "expiryDate": "2030-12-31",
              "issueDate": "2015-10-01",
              "issuingCountryCode": "DE",
              "kycTimestamp": "2025-11-20T15:30:45.123Z"
            },
            "biometricLiveness": {
              "livenessTimestamp": "2025-11-20T15:30:45.123Z"
            },
            "addressVerification": {
              "type": "NON_DOC"
            }
          }
        },
        "ownership": {
          "percentage": 100
        },
        "controllingPersonRole": "LP_OWNERSHIP",
        "taxResidences": [
          {
            "country": "ES",
            "tin": "48291734Z",
            "noTinReason": "UNABLE_TO_OBTAIN",
            "noTinExplanation": "Moved to Portugal in September 2026. The NIF application is still being processed."
          }
        ],
        "taxDeclaration": {
          "acceptedAt": "2026-10-20T09:15:00Z"
        }
      }
    ],
    "reliance": {
      "attestation": {
        "riskScore": "LOW",
        "eddCompleted": true
      }
    },
    "regulatorInformation": {
      "regulatorName": "Financial Conduct Authority",
      "regulatorJurisdiction": "DE"
    },
    "publicInformation": {
      "listedExchange": "London Stock Exchange",
      "tickerSymbol": "BVNK"
    }
  },
  "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1"
}

Response

Successful operation

referencestring uuid required

Unique identifier for the customer.

status'INFO_REQUIRED' | 'PENDING' | 'VERIFIED' | 'REJECTED' required

Current status of the customer.

INFO_REQUIRED: Customer information is needed for verification. A related questionnaire code is included in the response.
PENDING: Pending customer verification.
VERIFIED: Customer has been verified.
REJECTED: Verification has been unsuccessful.

Example response

{
  "reference": "0a184641-30e2-4414-871f-3db1c683900e",
  "status": "VERIFIED"
}

Changes

Nov 6, 2026c386d436bf2c Revision changes
- breaking
  removed the enum value NOT_PROVIDED of the request property //////
- breaking
  the ///// request property's minLength was increased from 0 to 2
- warning
  removed the request property /////
- warning
  added the new INFO_REQUIRED enum value to the response property for the response status
- info
  added the new optional request property ///////
- info
  added the new optional request property ////////
- info
  added the new optional request property ///////
- info
  added the new optional request property ///////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  the request property ///// became optional
- info
  the request property ///// became optional
- info
  request property ///// deprecated
- info
  added the new GIFT enum value to the request property //////
- info
  added the new STUDENT enum value to the request property //////
- info
  added the new STUDENT_LOAN enum value to the request property //////
Jun 16, 202697d6c0d2fe2e Revision changes
- breaking
  removed the enum value CUSTOMER_COLLECTIONS of the request property //////
- breaking
  removed the enum value INTERCOMPANY_TRANSFERS of the request property //////
- breaking
  removed the enum value TREASURY_MANAGEMENT of the request property //////
- breaking
  removed the enum value VENDOR_PAYMENTS of the request property //////
- warning
  removed the request property ////////
- warning
  removed the request property /////////
- warning
  removed the request property //////
- info
  added the new optional request property ///////
- info
  added the new optional request property ////////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new CUSTOMER_PAYMENTS_RECEIVED enum value to the request property //////
- info
  added the new CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS enum value to the request property //////
- info
  added the new DIVIDEND_PROFIT_DISTRIBUTIONS enum value to the request property //////
- info
  added the new INTERCOMPANY_TRANSFER enum value to the request property //////
- info
  added the new LOAN_REPAYMENT_FINANCIAL_ACTIVITIES enum value to the request property //////
- info
  added the new OPERATING_EXPENSES enum value to the request property //////
- info
  added the new SUPPLIER_VENDOR_PAYMENTS enum value to the request property //////

Operation history