--- title: "Create customer" method: POST path: "/platform/v2/customers" tags: ["Customers"] --- # Create customer `POST /platform/v2/customers` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/platform/v2/customers` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](/bvnk/api-explorer/endpoints/create-pre-customer-agreements-v-2), 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](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime). ::: ## Headers - `Idempotency-Key` string ## Request body - union: Create-customer request payload. Submit exactly one of `company` or `individual`; the customer type is inferred from the object you send. - object - `useCase` 'FIAT' | 'CRYPTO' | 'STABLECOIN_PAYOUTS' | 'EMBEDDED_STABLECOIN_WALLETS' | 'EMBEDDED_FIAT_ACCOUNTS', required - `reference` string: Partner-supplied reference. Unique within the caller's account. - `model` 'RELIANCE': Onboarding model. Omit for BVNK-Managed (default). Set to `RELIANCE` for Partner-Managed onboarding where the partner performs identity verification and passes metadata. - `company` V2CreateCompanyRequest, required: Corporate customer details. Required when creating a company customer. - `name` string, required: Legal name of the company. - `entityType` 'CORPORATION' | 'LIMITED_LIABILITY_COMPANY' | 'PUBLICLY_LISTED_COMPANY' | 'SOLE_PROPRIETOR' | 'PARTNERSHIP' | 'TRUST', required: Business entity type: - `CORPORATION`: Corporation - `LIMITED_LIABILITY_COMPANY`: Limited Liability Company - `PUBLICLY_LISTED_COMPANY`: Publicly listed company - `SOLE_PROPRIETOR`: Sole proprietor - `PARTNERSHIP`: Partnership - `TRUST`: Trust - `taxIdentification` object: Tax identification details of the company. **Required for US companies** (registered address or tax residence in the US). For US companies, `number` must be a valid EIN (`XX-XXXXXXX` or 9 digits). - `number` string, required: Tax identification number. For US residents, SSN or ITIN; for the rest of the world, the local tax number. - `taxResidenceCountryCode` string, required: Tax residence country as an ISO 3166-1 alpha-2 country code. - `registrationNumber` string, required: Official company registration number. 5–20 letters, digits, spaces, or hyphens. For US companies, this must be the EIN (`XX-XXXXXXX` or 9 digits). - `businessProfile` object, required: Business context and nature-of-business information. `naicsCode`, `monthlyExpectedVolumes`, and either `website` or `websiteExplanation` are required when creating a company. - `description` string: Short description of the company and its business activities. - `naicsCode` string, required: Industry classification of the company. Accepts a NAICS code (US and Mexico), a NACE code (EU and EEA), or an Industry API UUID. See the full list on the [Industry References](../../../references/industry-references/#list-of-references) page. **Required when creating a company.** - `monthlyExpectedVolumes` 'FROM_0_TO_10K' | 'FROM_10K_TO_50K' | 'FROM_50K_TO_100K' | 'FROM_100K_TO_1M' | 'FROM_1M_TO_10M' | 'ABOVE_10M', required: Business's expected monthly transaction volume: - `FROM_0_TO_10K`: 0 to 10,000 USD equivalent - `FROM_10K_TO_50K`: 10,000 to 50,000 USD equivalent - `FROM_50K_TO_100K`: 50,000 to 100,000 USD equivalent - `FROM_100K_TO_1M`: 100,000 to 1,000,000 USD equivalent - `FROM_1M_TO_10M`: 1,000,000 to 10,000,000 USD equivalent - `ABOVE_10M`: Above 10,000,000 USD equivalent **Required when creating a company.** - `website` string, uri: Website URL of the company. **Required when creating a company unless `websiteExplanation` is provided.** If the company has no website, omit this field and use `websiteExplanation` instead of a placeholder value such as `N/A`. A blank value counts as missing. You can send both fields. - `websiteExplanation` string: Explanation of why the company has no website, for example because it trades only through a mobile app. Compliance uses it to understand why there is no website to review. **Required when creating a company if `website` is not provided.** A blank value counts as missing. You can send both fields. - `isRegulated` boolean: Whether the company is regulated by a financial authority. If `true`, `regulatorInformation` with `regulatorName` and `regulatorJurisdiction` is required. Money-service businesses in some US states must be regulated to onboard. - `regulatorInformation` V2RegulatorInformation: Regulator information. Required when `isRegulated` is true. - `regulatorName` string: Name of the financial regulator overseeing the company. - `regulatorJurisdiction` string: Jurisdiction of the regulator as an ISO 3166-1 alpha-2 country code. - `regulatorRegisterNumber` string: Registration or licence number issued by the regulator. - `isPubliclyListed` boolean: Whether the company is publicly listed. If `true`, `publicInformation` with `listedExchange` and `tickerSymbol` is required. - `publicInformation` V2PublicInformation: Public-listing information. Required when `isPubliclyListed` is true. - `listedExchange` string: Name of the stock exchange where the company is listed. - `tickerSymbol` string: The company's ticker symbol on the exchange. - `sourceOfFunds` 'COMMERCIAL_ACTIVITIES' | 'SHAREHOLDER_CAPITAL' | 'VENTURE_CAPITAL' | 'SALE_OF_ASSETS' | 'CRYPTO_FUNDRAISING' | 'CRYPTO_TRADING_REVENUE' | 'CORPORATE_LOANS' | 'SALARY' | 'PENSION' | 'SAVINGS' | 'SELF_EMPLOYMENT' | 'GAMBLING' | 'REAL_ESTATE' | 'OTHER': Business's source of funds: - `COMMERCIAL_ACTIVITIES`: Revenue from commercial activities - `SHAREHOLDER_CAPITAL`: Shareholder capital contributions - `VENTURE_CAPITAL`: Venture capital funding - `SALE_OF_ASSETS`: Proceeds from sale of assets - `CRYPTO_FUNDRAISING`: Crypto fundraising proceeds - `CRYPTO_TRADING_REVENUE`: Revenue from crypto trading - `CORPORATE_LOANS`: Corporate loans - `SALARY`: Salary and employment income - `PENSION`: Pension and retirement income - `SAVINGS`: Savings and investments - `SELF_EMPLOYMENT`: Self employment and business income - `GAMBLING`: Gambling and lottery winnings - `REAL_ESTATE`: Real estate sales - `OTHER`: Other sources - `intendedUseOfAccount` 'SUPPLIER_VENDOR_PAYMENTS' | 'INTERCOMPANY_TRANSFERS' | 'PAYROLL' | 'CUSTOMER_PAYMENTS_RECEIVED' | 'CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS' | 'OPERATING_EXPENSES' | 'DIVIDEND_PROFIT_DISTRIBUTIONS' | 'LOAN_REPAYMENT_FINANCIAL_ACTIVITIES': Purpose of the business account: - `SUPPLIER_VENDOR_PAYMENTS`: Supplier and vendor payments - `INTERCOMPANY_TRANSFERS`: Intercompany transfers - `PAYROLL`: Payroll - `CUSTOMER_PAYMENTS_RECEIVED`: Customer payments received - `CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS`: Customer payouts, refunds, and settlements - `OPERATING_EXPENSES`: Operating expenses - `DIVIDEND_PROFIT_DISTRIBUTIONS`: Dividend and profit distributions - `LOAN_REPAYMENT_FINANCIAL_ACTIVITIES`: Loan repayment and financial activities - `address` object, required: Registered address of the company. `addressLine1`, `city`, `postalCode`, and `countryCode` are required; `stateCode` is required for US addresses. Companies registered in restricted countries are rejected. - `addressLine1` string, required: First line of the street address. - `addressLine2` string: Second line of the street address. Optional. - `city` string, required: City or locality. - `postalCode` string, required: Postal or ZIP code. - `stateCode` string: ISO 3166-2 subdivision code (US state). - `countryCode` string, required: ISO 3166-1 alpha-2 country code. - `isOperationalAddressDifferent` boolean: Whether the operational address of the company differs from the registered address. If `true`, `operationalAddress` is required. - `operationalAddress` object: Operational address of the company. **Required when `isOperationalAddressDifferent` is `true`**, with the same required fields as `address`. Operational addresses in restricted countries are rejected. - `addressLine1` string: First line of the street address. - `addressLine2` string: Second line of the street address. Optional. - `city` string: City or locality. - `postalCode` string: Postal or ZIP code. - `stateCode` string: ISO 3166-2 subdivision code (US state). - `countryCode` string: ISO 3166-1 alpha-2 country code. - `incorporationDate` string, date, required: Incorporation date of the company in the ISO-8601 format (`YYYY-MM-DD`). Must not be in the future. - `associates` V2CorporateCustomerAssociate[]: Associates of the corporate customer, such as UBOs, directors, signatories, control persons, and account representatives. - `id` string, uuid: Associate identifier. Returned on read and ignored on create. Use it with [Get associate](/bvnk/api-explorer/endpoints/get-customer-associate-v-2). - `person` V2AssociatePerson, required: Natural person associated with a corporate customer. - `firstName` string, required: First name of the associate. Must be 2–255 characters and must not contain digits. - `lastName` string, required: Last name of the associate. Must be 2–255 characters and must not contain digits. - `dateOfBirth` string, date, required: Date of birth in ISO-8601 format (`YYYY-MM-DD`). - `nationality` string: Nationality as an ISO 3166-1 alpha-2 code. **Required for associates of EEA companies and for associates with the `CONTROL_PERSON` title.** - `secondNationality` string: Second nationality as an ISO 3166-1 alpha-2 country code. Optional. - `birthCountryCode` string: Country of birth as an ISO 3166-1 alpha-2 code. **Required for associates of EEA companies and for associates with the `CONTROL_PERSON` title.** - `address` object, required: Residential address of the associate. `addressLine1`, `city`, `postalCode`, and `countryCode` are required; `stateCode` is required for US addresses. - `addressLine1` string, required: First line of the street address. - `addressLine2` string: Second line of the street address. Optional. - `city` string, required: City or locality. - `postalCode` string, required: Postal or ZIP code. - `stateCode` string: ISO 3166-2 subdivision code (US state). - `countryCode` string, required: ISO 3166-1 alpha-2 country code. - `contactInfo` object: Contact details of the associate. - `emailAddress` string, email: Email address. - `phoneNumber` string: Phone number in international format. - `taxIdentification` object, required: Tax identification details of the associate. For US persons (US nationality or US tax residence), `number` must be a valid SSN or ITIN. - `number` string, required: Tax identification number. For US residents, SSN or ITIN; for the rest of the world, the local tax number. - `taxResidenceCountryCode` string, required: Tax residence country as an ISO 3166-1 alpha-2 country code. - `position` string: Position or job title of the associate within the company. - `estimatedYearlyIncome` 'INCOME_0_TO_50K' | 'INCOME_50K_TO_100K' | 'INCOME_100K_TO_250K' | 'INCOME_250K_TO_500K' | 'INCOME_500K_TO_750K' | 'INCOME_750K_TO_1M' | 'INCOME_ABOVE_1M': Estimated yearly income band of the associate, in USD. - `controlOptions` object: The associate's control and authority over the company. - `canAppointDirectors` boolean, required - `hasSignificantControl` boolean, required - `controlsManagement` boolean, required - `controlsCorporateBody` boolean, required - `reliance` object: Verification evidence from your own KYC process. **Required for the `RELIANCE` (Partner-managed) model and rejected for the BVNK-Managed model.** For associates, `identityDocumentMetadata` is required when the associate's address is outside the US, and `biometricLiveness` is required when the associate's address is in the EEA. - `identityDocumentMetadata` object: Metadata about the identity document verified by the partner. **Required for EEA customers.** - … - `biometricLiveness` object: Biometric liveness check performed by the partner. **Required for EEA customers.** - … - `addressVerification` object, required: How the partner verified the customer's residential address. - … - `attestation` object, required: The partner's attestation of its risk assessment of the customer. - … - `titles` string[], required: Associate titles. At least one is required: - `UBO`: Ultimate Beneficial Owner - `BUSINESS_OWNER`: Business owner (beneficial owner). Treated the same as `UBO` - `CONTROL_PERSON`: Person with control over the entity - `SIGNATORY`: Authorized signatory - `DIRECTOR`: Company director - `ACCOUNT_REPRESENTATIVE`: Primary point of contact for the account - `ownership` object: Ownership details. **Required for associates with the `UBO` or `BUSINESS_OWNER` title and must not be provided for other associates.** The combined ownership of all associates must not exceed 100%. - `percentage` string, number, required: Ownership percentage held by the associate. A value between `0` and `100`. - `type` 'DIRECT' | 'INDIRECT', required: Type of ownership: - `DIRECT`: Directly held ownership - `INDIRECT`: Ownership held through an intermediary entity - `cdd` V2CompanyCustomerDueDiligence: Customer due-diligence (CDD) answers for a company customer. **Required for the `RELIANCE` (Partner-managed) model and rejected for the BVNK-Managed model.** When provided, `intendedUseOfAccount` and `pepStatus` are required; `expectedMonthlyVolume` is required for EEA companies. - `intendedUseOfAccount` 'SUPPLIER_VENDOR_PAYMENTS' | 'INTERCOMPANY_TRANSFERS' | 'PAYROLL' | 'CUSTOMER_PAYMENTS_RECEIVED' | 'CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS' | 'OPERATING_EXPENSES' | 'DIVIDEND_PROFIT_DISTRIBUTIONS' | 'LOAN_REPAYMENT_FINANCIAL_ACTIVITIES': Intended use of the account. - `pepStatus` 'NOT_PEP' | 'FORMER_PEP_2_YEARS' | 'FORMER_PEP_OLDER' | 'DOMESTIC_PEP' | 'FOREIGN_PEP' | 'CLOSE_ASSOCIATES' | 'FAMILY_MEMBERS' | 'STATE_OWNED': Politically Exposed Person (PEP) status. - `expectedMonthlyVolume` object: Expected monthly transaction volume. - `amount` number, required: Expected monthly volume amount. Must be non-negative. - `currency` 'USD' | 'EUR': Currency of `amount` (ISO 4217). Defaults to `USD` when omitted. - `reliance` V2CompanyRelianceMetadata: Your risk assessment of the company. **Required for the `RELIANCE` (Partner-managed) model and rejected for the BVNK-Managed model.** - `attestation` object, required: Your attestation of the company's risk assessment. - `riskScore` 'LOW' | 'MEDIUM' | 'HIGH', required: Risk score you assigned to the company. - `eddCompleted` boolean, required: Whether Enhanced Due Diligence (EDD) was completed. - object - `useCase` 'FIAT' | 'CRYPTO' | 'STABLECOIN_PAYOUTS' | 'EMBEDDED_STABLECOIN_WALLETS' | 'EMBEDDED_FIAT_ACCOUNTS', required - `reference` string: Partner-supplied reference. Unique within the caller's account. - `model` 'RELIANCE': Onboarding model. Omit for BVNK-Managed (default). Set to `RELIANCE` for Partner-Managed onboarding where the partner performs identity verification and passes metadata. - `individual` V2CreateIndividualRequest, required: Individual customer details. Required when creating an individual customer. An **EEA customer** is one onboarded under a BVNK EEA entity whose residential address is in an EEA country. Additional fields are required for EEA customers, US customers, and US residents of certain states, as noted on each field. - `firstName` string, required: First name. Must be 2–255 characters and must not contain digits. - `lastName` string, required: Last name. Must be 2–255 characters and must not contain digits. - `emailAddress` string, email, required: Email address. - `phoneNumber` string: Phone number in international format. - `description` string: Additional notes or description of this individual customer. This field can include relevant background information, special requirements, customer preferences, account purpose, or any other details that may be helpful for future reference. - `dateOfBirth` string, date, required: Date of birth in ISO-8601 format (`YYYY-MM-DD`). Must not be in the future. - `placeOfBirth` string: Place of birth (city or locality). - `birthCountryCode` string: Country of birth as an ISO 3166-1 alpha-2 code. **Required for EEA customers.** - `nationality` string: Nationality as an ISO 3166-1 alpha-2 code. **Required for EEA customers.** Customers with a restricted nationality are rejected. - `documentNumber` string: Identification document number (for example, passport or national ID). 5–20 letters, digits, spaces, or hyphens. Must be unique within your account for the same country of birth. - `documentInfo` V2IndividualDocumentInfo: Identity document reference for an individual customer. When provided for the BVNK-Managed model, `type` and `issuingCountryCode` are required. - `number` string: Document number. - `type` 'PASSPORT' | 'ID_CARD' | 'DRIVERS' | 'RESIDENCE_PERMIT' | 'OTHER': Document type. - `issuingCountryCode` string: Issuing country as an ISO 3166-1 alpha-2 code. - `address` object, required: Residential address of the individual. `addressLine1`, `city`, `postalCode`, and `countryCode` are required. - `stateCode` is **required for US addresses** and must be a valid two-letter US state or territory code. - `postalCode` format is validated for US (`12345` or `12345-6789`), GB, CN, and JP addresses. - Placeholder values such as `n/a`, `none`, or `test` are rejected in address lines. - Addresses in restricted countries are rejected. - `addressLine1` string, required: First line of the street address. - `addressLine2` string: Second line of the street address. Optional. - `city` string, required: City or locality. - `postalCode` string, required: Postal or ZIP code. - `stateCode` string: ISO 3166-2 subdivision code (US state). - `countryCode` string, required: ISO 3166-1 alpha-2 country code. - `taxIdentification` object, required: Tax identification details. **Required for all individual customers.** For US persons (US nationality or US tax residence), `number` must be a valid SSN (`123-45-6789`) or ITIN (`9XX-XX-XXXX`). - `number` string, required: Tax identification number. For US residents, SSN or ITIN; for the rest of the world, the local tax number. - `taxResidenceCountryCode` string, required: Tax residence country as an ISO 3166-1 alpha-2 country code. - `cdd` object: Customer Due Diligence (CDD) details. **Required.** - `employmentStatus` 'SALARIED' | 'SELF_EMPLOYED' | 'UNEMPLOYED' | 'RETIRED' | 'STUDENT' | 'NOT_PROVIDED': Employment status. **Required.** - `SALARIED`: Salaried - `SELF_EMPLOYED`: Self employed and freelancer - `UNEMPLOYED`: Unemployed - `RETIRED`: Retired - `STUDENT`: Student - `NOT_PROVIDED`: Not provided - `sourceOfFunds` 'SALARY' | 'PENSION' | 'SAVINGS' | 'SELF_EMPLOYMENT' | 'CRYPTO_TRADING' | 'GAMBLING' | 'REAL_ESTATE' | 'GIFT' | 'STUDENT_LOAN_GRANT': Source of funds. **Required.** - `SALARY`: Salary and employment income - `PENSION`: Pension and retirement income - `SAVINGS`: Savings and investments - `SELF_EMPLOYMENT`: Self employment and business income - `CRYPTO_TRADING`: Crypto trading - `GAMBLING`: Gambling and lottery winnings - `REAL_ESTATE`: Real estate sales - `GIFT`: Gift or inheritance - `STUDENT_LOAN_GRANT`: Student loan or grant - `pepStatus` 'NOT_PEP' | 'FORMER_PEP_2_YEARS' | 'FORMER_PEP_OLDER' | 'DOMESTIC_PEP' | 'FOREIGN_PEP' | 'CLOSE_ASSOCIATES' | 'FAMILY_MEMBERS' | 'STATE_OWNED': Politically Exposed Person status. **Required.** - `NOT_PEP`: Not a PEP - `FORMER_PEP_2_YEARS`: Former or inactive PEP (within 2 years) - `FORMER_PEP_OLDER`: Former or inactive PEP (older than 2 years) - `DOMESTIC_PEP`: Domestic PEP - `FOREIGN_PEP`: Foreign PEP - `CLOSE_ASSOCIATES`: Close associates - `FAMILY_MEMBERS`: Family members - `STATE_OWNED`: State-owned entity (entity only) - `intendedUseOfAccount` 'TRANSFERS_OWN_WALLET' | 'TRANSFERS_FAMILY_FRIENDS' | 'INVESTMENTS' | 'GOODS_SERVICES' | 'DONATIONS': Purpose of the account. **Required.** - `TRANSFERS_OWN_WALLET`: Transfers to or from own wallet including bank accounts - `TRANSFERS_FAMILY_FRIENDS`: Transfers to or from family and friends - `INVESTMENTS`: Investments - `GOODS_SERVICES`: Purchases of goods and services - `DONATIONS`: Donations - `expectedMonthlyVolume` object: Expected monthly transaction volume. **Required for EEA customers.** - `amount` number, required: Expected monthly volume amount. Must be non-negative. - `currency` 'USD' | 'EUR': Currency of `amount` (ISO 4217). Defaults to `USD` when omitted. - `estimatedYearlyIncome` 'INCOME_0_TO_50K' | 'INCOME_50K_TO_100K' | 'INCOME_100K_TO_250K' | 'INCOME_250K_TO_500K' | 'INCOME_500K_TO_750K' | 'INCOME_750K_TO_1M' | 'INCOME_ABOVE_1M': Estimated yearly income band, in USD. **Required for US residents of states where crypto services for individuals are provided through Paxos.** - `employmentIndustrySector` 'INVESTMENT' | 'HEDGE_FUND' | 'MONEY_SERVICE_BUSINESS' | 'STO_ISSUER' | 'PRECIOUS_METALS' | 'NON_PROFIT' | 'REGISTERED_INVESTMENT_ADVISOR' | 'AGRICULTURE_FORESTRY_FISHING_HUNTING' | 'MINING' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_WAREHOUSING' | 'INFORMATION' | 'FINANCE_INSURANCE' | 'REAL_ESTATE_RENTAL_LEASING' | 'PROFESSIONAL_SCIENTIFIC_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_ENTERPRISES' | 'ADMINISTRATIVE_SUPPORT_WASTE_MANAGEMENT_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_RECREATION' | 'ACCOMMODATION_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' | 'NOT_CLASSIFIED' | 'ADULT_ENTERTAINMENT' | 'AUCTIONS' | 'AUTOMOBILES' | 'BLOCKCHAIN' | 'CRYPTO' | 'DRUGS' | 'EXPORT_IMPORT' | 'E_COMMERCE' | 'FINANCIAL_INSTITUTION' | 'GAMBLING' | 'INSURANCE' | 'MARKET_MAKER' | 'SHELL_BANK' | 'TRAVEL_TRANSPORT' | 'WEAPONS': Industry sector of the individual's employment. **Required for US residents of states where crypto services for individuals are provided through Paxos.** - `reliance` V2PersonRelianceMetadata: Verification evidence from the partner's own KYC process. **Required for the `RELIANCE` (Partner-managed) model and rejected for the BVNK-Managed model.** - `identityDocumentMetadata` object: Metadata about the identity document verified by the partner. **Required for EEA customers.** - `type` 'PASSPORT' | 'ID_CARD' | 'DRIVERS' | 'RESIDENCE_PERMIT' | 'OTHER', required: Identity document type. - `number` string, required: Document number. - `issueDate` string, date: Document issue date. - `expiryDate` string, date: Document expiry date. **Required unless `type` is `ID_CARD` or `OTHER`.** - `issuingCountryCode` string, required: Issuing country as an ISO 3166-1 alpha-2 code. Must not be a restricted country. - `kycTimestamp` string, date-time, required: When the partner completed the KYC check. Must be within the last 5 years and not in the future. - `biometricLiveness` object: Biometric liveness check performed by the partner. **Required for EEA customers.** - `livenessTimestamp` string, date-time, required: When the liveness check was completed. - `addressVerification` object, required: How the partner verified the customer's residential address. - `type` 'DOC' | 'NON_DOC', required: - `DOC`: Verified with a proof-of-address document - `NON_DOC`: Verified with a non-documentary check - `attestation` object, required: The partner's attestation of its risk assessment of the customer. - `riskScore` 'LOW' | 'MEDIUM' | 'HIGH', required: Risk score assigned by the partner. - `eddCompleted` boolean, required: Whether Enhanced Due Diligence (EDD) was completed. ## Response `201` Customer onboarding application created - V2CustomerResponse: Customer details. - `id` string, uuid - `reference` string - `status` 'AGREEMENTS_PENDING' | 'INFO_REQUIRED' | 'PENDING' | 'ACTIONS_REQUIRED' | 'VERIFIED' | 'REJECTED' | 'TERMINATED': Customer onboarding status: - `AGREEMENTS_PENDING`: The customer was created through [pre-customer agreements](/bvnk/api-explorer/endpoints/create-pre-customer-agreements-v-2) 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' - `name` string - `createdAt` string, date-time - `updatedAt` string, date-time - `authenticatedLink` V2AuthenticatedLinkResponse: Authenticated deep-link for the customer. - `link` string: Authenticated link URL. - `expiresAt` string, date-time: Link expiration timestamp. - `requiredActions` V2RequiredAction[]: Actions the partner or customer must take to progress onboarding. Empty when the customer is in a terminal state or no actions are pending. Omitted when the upstream status is temporarily unavailable. - `type` 'DATA' | 'USER_ROLE' | 'BLOCKER': Kind of action required: - `DATA`: Information, a document, or an agreement response is missing. - `USER_ROLE`: An action is required from a specific user role. - `BLOCKER`: An internal step (for example, a manual compliance review) must be completed by BVNK. No action from you is possible. - `code` string: Stable machine-readable identifier (UPPER_SNAKE_CASE). - `category` string: Category of the requested information. Present only for `type=DATA`. Common values: - `GET_STARTED` - `COMPANY_INFORMATION` - `NATURE_OF_BUSINESS` - `DOCUMENT_REQUIREMENTS`: A document must be uploaded. See `target` for the accepted document types. - `RISK_WARNING` - `SELF_CATEGORISATION` - `APPROPRIATENESS_TEST` - `ASSOCIATES` - `AGREEMENTS`: An agreement must be accepted. See `target` for the agreement. Other categories may be returned; treat unknown values as generic data requests. - `description` string: Human-readable label, when available. - `status` 'REQUIRED' | 'PROCESSING': Fulfilment status of the action. Present only for `type=DATA`. - `target` union: Resumable handle identifying the specific agreement, document, or field the action relates to. Discriminated by `kind`. Present when upstream carries enough signal to identify the target; omitted otherwise. - V2RequiredActionTargetAgreement: Target pointing to a specific agreement the customer must accept. - `kind` 'AGREEMENT': Discriminator value. - `assignedAgreementId` string, uuid: ID of the assigned agreement instance. - `urn` string: Agreement URN. - `version` string: Agreement version. - `title` string: Human-readable agreement title. - `locale` string: Locale of the agreement text (e.g. `en`). - V2RequiredActionTargetDocument: Target pointing to a specific document requirement. - `kind` 'DOCUMENT': Discriminator value. - `docSetType` string: Document set type code. - `types` string[]: Acceptable document types. - `subTypes` string[]: Acceptable document sub-types. - `associateId` string, uuid: Associate ID when the document relates to a specific associate; `null` for company-level documents. - V2RequiredActionTargetField: Target pointing to a specific data field that must be supplied. - `kind` 'FIELD': Discriminator value. - `path` string: Dot-notation path to the required field. - `associateId` string, uuid: Associate ID when the field relates to a specific associate; `null` for company-level fields. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Your account is not enabled for this customer type or use case. - `409`: Idempotency key re-used with a different payload, the `reference` is already in use, or the customer for this `reference` was already submitted. - `429`: A request with the same `Idempotency-Key` is still being processed. Retry after it completes. ## Changes - **2026-11-06** `c386d436bf2c`: 5 warning, 11 info - removed the request property `company` - removed the request property `individual` - added the new `AGREEMENTS_PENDING` enum value to the `status` response property for the response status `201` - added the new `EMBEDDED` enum value to the `model` response property for the response status `201` - …12 more - **2026-06-16** `97d6c0d2fe2e`: 1 info - endpoint added [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/platform/v2/customers/post.md) --- [API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)