Customers

Create customer

Changed on Nov 6, 2026

Initiates a new customer onboarding application. Submit either a company or individual object, along with the useCase. The customer type is determined by the object provided.

Jurisdiction guidance:

For EEA customers, provide associate nationality, birth country, and biometric or selfie evidence. Individual EEA customers must include nationality, birthCountryCode, and cdd.expectedMonthlyVolume.
For US customers, supply US tax identifiers where applicable. Additional fields may be required for control persons. Individual US persons (US nationality or US tax residence) must provide a valid SSN or ITIN in taxIdentification.number, and address.stateCode for US addresses.
Some US states require individual customers to provide cdd.estimatedYearlyIncome and cdd.employmentIndustrySector.

If you have created pre-customer agreements, use the same reference here. Agreements must be signed before the customer can be created.

Field-level validation failures return a 400 status with error code bvnk:onboarding-accounts:4016 and a details.errors map indicating field paths and messages.

Onboarding is completed automatically once all required company documents, associate identification documents, questionnaires, and assigned agreements are submitted and accepted for processing.

:::warning Before using this endpoint, ensure you are not onboarding customers from restricted jurisdictions. For details, see the BVNK Acceptable Use Policy. :::

post/platform/v2/customers

Request

Base URL
https://api.sandbox.bvnk.com
Auth
HTTP bearer
TypeScript
https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/platform/v2/customers/post.ts
A function with typed inputs. Its response is checked against the schema.

Headers

Idempotency-Keystring

Client-supplied idempotency key.

Request body

Example request

{
  "useCase": "STABLECOIN_PAYOUTS",
  "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01",
  "model": "RELIANCE",
  "company": {
    "name": "Krause Fintech GmbH",
    "entityType": "CORPORATION",
    "taxIdentification": {
      "number": "21/815/08150",
      "taxResidenceCountryCode": "DE"
    },
    "registrationNumber": "HRB 123456",
    "businessProfile": {
      "description": "German fintech company specializing in payment solutions and financial software",
      "naicsCode": "5411",
      "monthlyExpectedVolumes": "FROM_100K_TO_1M",
      "website": "https://www.krause-fintech.de",
      "websiteExplanation": "Trades only through a mobile app and has no public website.",
      "isRegulated": true,
      "regulatorInformation": {
        "regulatorName": "BaFin",
        "regulatorJurisdiction": "DE",
        "regulatorRegisterNumber": "108060"
      },
      "publicInformation": {
        "listedExchange": "NYSE",
        "tickerSymbol": "ACME"
      },
      "sourceOfFunds": "COMMERCIAL_ACTIVITIES",
      "intendedUseOfAccount": "SUPPLIER_VENDOR_PAYMENTS"
    },
    "address": {
      "addressLine1": "Heidestrasse 19",
      "city": "Koeln",
      "postalCode": "51247",
      "stateCode": "NY",
      "countryCode": "DE"
    },
    "operationalAddress": {
      "addressLine1": "Heidestrasse 19",
      "city": "Koeln",
      "postalCode": "51247",
      "stateCode": "NY",
      "countryCode": "DE"
    },
    "incorporationDate": "2019-01-15",
    "associates": [
      {
        "person": {
          "firstName": "Freya",
          "lastName": "Krause",
          "dateOfBirth": "1982-03-24",
          "nationality": "DE",
          "birthCountryCode": "DE",
          "address": {
            "addressLine1": "Heidestrasse 19",
            "city": "Koeln",
            "postalCode": "51247",
            "stateCode": "NY",
            "countryCode": "DE"
          },
          "contactInfo": {
            "emailAddress": "freya.krause@krause-fintech.de",
            "phoneNumber": "+4915112345678"
          },
          "taxIdentification": {
            "number": "21/815/08150",
            "taxResidenceCountryCode": "DE"
          },
          "position": "Geschaeftsfuehrer",
          "estimatedYearlyIncome": "INCOME_100K_TO_250K",
          "reliance": {
            "identityDocumentMetadata": {
              "type": "PASSPORT",
              "number": "C01X00T47",
              "issueDate": "2021-03-01",
              "expiryDate": "2031-02-28",
              "issuingCountryCode": "DE",
              "kycTimestamp": "2026-04-20T09:15:00Z"
            },
            "biometricLiveness": {
              "livenessTimestamp": "2026-04-20T09:16:30Z"
            },
            "addressVerification": {
              "type": "NON_DOC"
            },
            "attestation": {
              "riskScore": "LOW"
            }
          }
        },
        "ownership": {
          "percentage": "100",
          "type": "DIRECT"
        }
      }
    ],
    "cdd": {
      "intendedUseOfAccount": "SUPPLIER_VENDOR_PAYMENTS",
      "pepStatus": "NOT_PEP",
      "expectedMonthlyVolume": {
        "amount": 10000,
        "currency": "EUR"
      }
    },
    "reliance": {
      "attestation": {
        "riskScore": "LOW"
      }
    }
  }
}

Response

Customer onboarding application created

idstring uuid

referencestring

Customer onboarding status:

AGREEMENTS_PENDING: The customer was created through pre-customer agreements and the agreements are not yet signed.
INFO_REQUIRED: Customer data, documents, or agreements are still missing. Check requiredActions.
PENDING: All information is submitted and the customer is under review.
ACTIONS_REQUIRED: Additional information is requested during or after review. Check requiredActions.
VERIFIED: The customer is verified.
REJECTED: The customer failed verification.
TERMINATED: The customer was offboarded.

type'COMPANY' | 'INDIVIDUAL'

model'EMBEDDED' | 'RELIANCE'

The onboarding model of the customer. EMBEDDED indicates BVNK-Managed onboarding, where BVNK performs identity verification. RELIANCE indicates Partner-Managed onboarding, where you perform identity verification.

useCase'FIAT' | 'CRYPTO' | 'STABLECOIN_PAYOUTS' | 'EMBEDDED_STABLECOIN_WALLETS' | 'EMBEDDED_FIAT_ACCOUNTS'

namestring

createdAtstring date-time

updatedAtstring date-time

Example response

{
  "id": "0a184641-30e2-4414-871f-3db1c683900e",
  "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01",
  "status": "PENDING",
  "type": "COMPANY",
  "model": "EMBEDDED",
  "useCase": "STABLECOIN_PAYOUTS",
  "name": "Krause Fintech GmbH",
  "requiredActions": [
    {
      "status": "REQUIRED",
      "target": {
        "kind": "AGREEMENT",
        "assignedAgreementId": "a3c1f9d2-84b7-4e1a-9f6c-2d8e5b7a4c01",
        "urn": "bvnk:agreements:terms-of-service",
        "version": "2.1",
        "title": "Terms of Service",
        "locale": "en"
      }
    }
  ]
}

Changes

Nov 6, 2026c386d436bf2c Revision changes
- warning
  removed the request property
- warning
  removed the request property
- warning
  added the new AGREEMENTS_PENDING enum value to the response property for the response status
- warning
  added the new EMBEDDED enum value to the response property for the response status
- warning
  added the new RELIANCE enum value to the response property for the response status
- info
  added the new optional request property
- info
  added subschema #1: Company customer subschema #2: Individual customer to the request body oneOf list
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  removed the non-success response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  removed the CUSTOMER_VIRTUAL_ACCOUNTS enum value from the response property for the response status
- info
  removed the DOUBLE_EMBEDDED enum value from the response property for the response status
- info
  removed the EMBEDDED_BVNK_MANAGED enum value from the response property for the response status
- info
  removed the EMBEDDED_SELF_MANAGED enum value from the response property for the response status
Jun 16, 202697d6c0d2fe2e Revision changes
- info
  endpoint added

Operation history