--- title: "Upload customer documents" method: POST path: "/platform/v2/customers/{customerId}/documents" tags: ["Manage Documents"] --- # Upload customer documents `POST /platform/v2/customers/{customerId}/documents` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/platform/v2/customers/{customerId}/documents` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Uploads 1-3 documents for a customer as `multipart/form-data`: company-level KYB documents for a `company` customer, or identity and supporting documents for an `individual` customer. The `metadata` field is a JSON array. Each file in the files field must correspond to a metadata entry in the same order. For an `individual` customer onboarded with the BVNK-Managed model, submit documents for identity verification. For each document: - `countryCode` (the document's issuing country) is **required**. Requests without it are rejected with `400` (error code `bvnk:onboarding-accounts:4022`). - For two-sided documents, such as `ID_CARD`, `DRIVERS`, `RESIDENCE_PERMIT`, upload each side separately. Set `subType` to `FRONT_SIDE` or `BACK_SIDE` as appropriate. - Use `SELFIE` for a selfie, and `UTILITY_BILL` or `BANK_STATEMENT` for proof of address. The `requiredActions` field specifies which documents are needed. For `individual` customers onboarded with the `RELIANCE` (Partner-managed) model, upload only the documents listed in `requiredActions`, such as during Enhanced Due Diligence. For customers created through [pre-customer agreements](/bvnk/api-explorer/endpoints/create-pre-customer-agreements-v-2), upload documents only after the agreements are signed. Otherwise error code `bvnk:onboarding-accounts:4023` is returned. For `company` customers, use this endpoint to submit initial mandatory KYB files and any conditional or risk-triggered documents, such as Source of Wealth, AML policy, or regulatory licence. If a document is later rejected, re-upload the corrected file to replace the previous submission. Best practice: upload documents one at a time and add a one-second delay between uploads to reduce rate-limit pressure. ## Path parameters - `customerId` string, uuid, required ## Request body `multipart/form-data` - V2CustomerDocumentsUploadRequest - `metadata` V2CustomerDocumentMetadata[], required: One metadata entry per uploaded file. Order must match `files`. - `type` 'CERTIFICATE_OF_INCORPORATION' | 'MEMORANDUM' | 'ARTICLE_OF_ASSOCIATION' | 'PROOF_OF_DIRECTORSHIP' | 'CORPORATE_STRUCTURE' | 'PROOF_OF_OPERATIONAL_ADDRESS' | 'SOURCE_OF_FUNDS' | 'SOURCE_OF_WEALTH' | 'COMPANY_SOURCE_OF_WEALTH' | 'UBO_SOURCE_OF_WEALTH' | 'UBO_ADDRESS_VERIFICATION' | 'DIRECTOR_ADDRESS_VERIFICATION' | 'TRANSPARENCY_REGISTRY_EXTRACT' | 'POWER_OF_ATTORNEY' | 'COMPANY_DOC' | 'OTHER' | 'PASSPORT' | 'ID_CARD' | 'DRIVERS' | 'RESIDENCE_PERMIT' | 'SELFIE' | 'UTILITY_BILL' | 'BANK_STATEMENT' | 'PROOF_OF_RESIDENTIAL_ADDRESS' | 'PROOF_OF_FUNDS_SAVINGS' | 'PROOF_OF_PROFESSIONAL_ACTIVITY', required: Document type. Supported company document types: | Type | Description | When required | | --- | --- | --- | | `CERTIFICATE_OF_INCORPORATION` | Certificate of incorporation or business formation document. | Mandatory (US + EU BVNK-Managed, US Partner-managed) | | `MEMORANDUM` | Memorandum of Association. | Mandatory (BVNK-Managed) | | `ARTICLE_OF_ASSOCIATION` | Articles of Association. | Mandatory (BVNK-Managed) | | `PROOF_OF_DIRECTORSHIP` | Registry extract or certified register of directors. | Mandatory (BVNK-Managed) | | `CORPORATE_STRUCTURE` | Ownership chart showing all shareholders through to UBOs. | Mandatory (BVNK-Managed) | | `PROOF_OF_OPERATIONAL_ADDRESS` | Utility bill, lease contract, or equivalent (dated within 3 months). | Required if operational address differs from registered | | `SOURCE_OF_FUNDS` | Bank statements (3 months activity) or equivalent SoF evidence. | May be requested during compliance review | | `SOURCE_OF_WEALTH` | Audited accounts, tax returns, loan agreements. | Conditional (high risk or EDD) | | `COMPANY_SOURCE_OF_WEALTH` | Evidence of the company's source of wealth. | Conditional (high risk or EDD) | | `UBO_SOURCE_OF_WEALTH` | Evidence of a UBO's source of wealth. | Conditional (high risk or EDD) | | `UBO_ADDRESS_VERIFICATION` | Proof of residential address for a UBO. | May be requested during compliance review | | `DIRECTOR_ADDRESS_VERIFICATION` | Proof of residential address for a director. | May be requested during compliance review | | `TRANSPARENCY_REGISTRY_EXTRACT` | Extract from a transparency or beneficial-ownership register. | May be requested during compliance review | | `POWER_OF_ATTORNEY` | Power of attorney for a person acting on behalf of the company. | May be requested during compliance review | | `COMPANY_DOC` / `OTHER` | Any other company document. | When requested | | `PASSPORT` / `ID_CARD` / `DRIVERS` / `RESIDENCE_PERMIT` | Government-issued ID for associates. | Required for associate verification | | `SELFIE` | Biometric selfie/liveness for associate verification. | Required for associate verification | | `UTILITY_BILL` | Proof of residential address for associates. | Required for associate verification | Supported individual document types: | Type | Description | When required | | --- | --- | --- | | `PASSPORT` | Passport (photo page). | Identity verification | | `ID_CARD` / `DRIVERS` / `RESIDENCE_PERMIT` | National ID card, driving licence, or residence permit. Upload `FRONT_SIDE` and `BACK_SIDE` separately. | Identity verification | | `SELFIE` | Selfie of the individual. | Identity verification | | `UTILITY_BILL` / `BANK_STATEMENT` | Proof of residential address issued within the last 3 months. | Address verification, when requested | | `SOURCE_OF_WEALTH` / `PROOF_OF_FUNDS_SAVINGS` / `PROOF_OF_PROFESSIONAL_ACTIVITY` | Evidence of source of wealth, savings, or professional activity. | Conditional (high risk or EDD) | - `filename` string, required - `description` string - `subType` string: Document side for two-sided individual identity documents. - `FRONT_SIDE`: Front side - `BACK_SIDE`: Back side - `countryCode` string: Issuing country of the document as an ISO 3166-1 alpha-2 code. **Required for every document uploaded for an individual customer onboarded with the BVNK-Managed model.** - `files` string[], required: One file per metadata entry, in matching order. ## Response `202` Documents accepted for processing - V2UploadCustomerDocumentsResponse: Batch response for a company-document upload. - `id` string, uuid: Batch correlation id for tracing; not a persistent lookup key. - `customerId` string, uuid - `totalDocuments` integer - `successCount` integer - `failureCount` integer - `documents` V2CustomerDocumentResult[] - `documentId` string, uuid: Persistent document id. Use this handle for follow-up document calls. - `type` string - `filename` string - `description` string - `status` 'STORED' | 'FAILED' - `uploadedAt` string, date-time - `errorMessage` string: Error message when `status=FAILED`; null when `STORED`. - `createdAt` string, date-time ## Other responses - `400`: Bad Request - `401`: Unauthorized - `404`: The specified resource was not found ## Changes - **2026-11-06** `c386d436bf2c`: 3 breaking, 16 info - removed the enum value `AML_POLICY` of the request property `metadata/items/type` - removed the enum value `PROOF_OF_REGULATORY_LICENSE` of the request property `metadata/items/type` - removed the enum value `SHAREHOLDER_OWNERSHIP` of the request property `metadata/items/type` - api operation id `uploadCustomerCompanyDocumentsV2` removed and replaced with `uploadCustomerDocumentsV2` - …15 more - **2026-06-16** `97d6c0d2fe2e`: 1 info - endpoint added [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/platform/v2/customers/:customerId/documents/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)