--- title: "Update customer" method: PATCH path: "/platform/v2/customers/{id}" tags: ["Customers"] --- # Update customer `PATCH /platform/v2/customers/{id}` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/platform/v2/customers/{id}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Applies a partial update to a customer's onboarding data. Omitted fields are left unchanged. Submit the `company` object for a company customer or the `individual` object for an individual customer, never both. A body that does not match the customer's type is rejected with `400` (error code `bvnk:onboarding-accounts:4021`). :::info Updates are only permitted while the customer is in the `INFO_REQUIRED` status and before the customer has submitted their onboarding information. In any other status, the request is rejected with `400` (error code `bvnk:onboarding-accounts:4004`). ::: The same field validation rules as [Create customer](/bvnk/api-explorer/endpoints/create-customer-v-2) apply to the updated values, for example, SSN/ITIN format checks for US persons and uniqueness of `documentNumber`. Customers onboarded with Customers API v.1 can't be updated with this endpoint; the request is rejected with `400` (error code `bvnk:onboarding-accounts:4017`). Associates can't be changed with this endpoint. Use [Update customer associate](/bvnk/api-explorer/endpoints/update-customer-associate-v-2) instead. ## Path parameters - `id` string, uuid, required ## Request body - union: Update-customer payload. Submit `company` for a company customer or `individual` for an individual customer, never both. To update only `reference`, omit both. All fields are optional; omitted fields are left unchanged. - object - `reference` string: Updated partner-supplied reference. Must remain unique within the caller's account. - `company` V2UpdateCompanyRequest, required: Fields to update on a company customer. Every field is optional; omitted fields are left unchanged. Associates cannot be changed here. Use the [associate endpoints](/bvnk/api-explorer/endpoints/create-customer-associate-v-2) instead. - `name` string: Legal name of the company. - `entityType` 'CORPORATION' | 'LIMITED_LIABILITY_COMPANY' | 'PUBLICLY_LISTED_COMPANY' | 'SOLE_PROPRIETOR' | 'PARTNERSHIP' | 'TRUST': 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. 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: 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: Business context, customer due diligence data, and nature-of-business information. - `description` string: Short description of the company and its business activities. - `naicsCode` string: 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': 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: Registered address of the company. When provided, `addressLine1`, `city`, `postalCode`, and `countryCode` are required; `stateCode` is required for US addresses. - `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. - `isOperationalAddressDifferent` boolean: Whether the operational address differs from the registered address. - `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: Date of incorporation in ISO-8601 format (`YYYY-MM-DD`). Must not be in the future. - `cdd` object: Customer due-diligence answers. Only applicable to the `RELIANCE` (Partner-managed) model. - `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. - object - `reference` string: Updated partner-supplied reference. Must remain unique within the caller's account. - `individual` V2UpdateIndividualRequest, required: Fields to update on an individual customer. Every field is optional; omitted fields are left unchanged. Supplied values are validated with the same rules as on creation. - `firstName` string: First name. - `lastName` string: Last name. - `emailAddress` string, email: 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: 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: 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: 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. - `taxIdentification` object: Tax identification details. 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. - `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 `200` Customer updated - V2UpdateCustomerResponse: 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. - `verificationLink` string, uri: Identity verification (KYC) link. Returned for individual customers onboarded with the BVNK-Managed model. Send it to your customer so they can complete identity verification. The link doesn't expire: it stays active and is refreshed automatically. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `404`: The specified resource was not found - `409`: The supplied `reference` is already in use by another customer on the same account. ## Changes - **2026-11-06** `c386d436bf2c`: 1 info - endpoint added [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/platform/v2/customers/:id/patch.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)