--- title: "Upload documents to customer" method: POST path: "/platform/v1/customers/{customerReference}/documents" tags: ["Customers"] --- # Upload documents to customer `POST /platform/v1/customers/{customerReference}/documents` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/platform/v1/customers/{customerReference}/documents` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) :::info Customers API v2 The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) 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. ::: Attach one or more documents to a customer's profile. This can be either a company customer (with optional linkage to a specific associate) or an individual customer. Files must be base64-encoded before submission. - For company-level documents, omit `customerPersonReference`. - For associate-level documents, provide the `customerPersonReference`. - The customer must be in `INFO_REQUIRED` status. ## Path parameters - `customerReference` string, required ## Request body - union[] - union - object: Company-level document for a business customer. - `customerPersonReference` string, uuid: Unique identifier of associate (beneficial owner, director, etc.) the document belongs to. Omit to attach the document to the company itself. - `type` 'COMPANY_DOC' | 'TRANSPARENCY_REGISTRY_EXTRACT' | 'POWER_OF_ATTORNEY', required: Company-level document type: - `COMPANY_DOC`: Generic company document. Use `subType` to indicate the specific document (incorporation certificate, memorandum, articles of association, directors' registry, source of funds, regulatory licence, etc.). - `TRANSPARENCY_REGISTRY_EXTRACT`: Extract from the transparency / beneficial ownership registry. - `POWER_OF_ATTORNEY`: Power of attorney authorising a representative. - `subType` 'CAPITALISATION_OWNERSHIP_STRUCTURE' | 'DIRECTORS_REGISTRY' | 'GOOD_STANDING_CERT' | 'INCORPORATION_ARTICLES' | 'INCORPORATION_CERT' | 'INCUMBENCY_CERT' | 'INFORMATION_STATEMENT' | 'MEMORANDUM' | 'PARTNERSHIP_AGREEMENT' | 'POWER_OF_ATTORNEY' | 'PROOF_OF_ADDRESS' | 'PROOF_OF_NATURE_OF_BUSINESS' | 'REGULATORY_LICENSE' | 'SELF_DECLARATION_FORM' | 'SHAREHOLDER_REGISTRY' | 'SOURCE_OF_FUNDS' | 'STATE_REGISTRY' | 'TRADE_LICENSE' | 'TRUST_AGREEMENT' | 'OTHER': Subtype of document. Required with `COMPANY_DOC` to indicate the specific company document. - `CAPITALISATION_OWNERSHIP_STRUCTURE`: Corporate/group structure or ownership documentation for complex structures - `DIRECTORS_REGISTRY`: Directors' registry or proof of directorship - `GOOD_STANDING_CERT`: Certificate of good standing - `INCORPORATION_ARTICLES`: Articles of Association - `INCORPORATION_CERT`: Certificate of incorporation or business formation - `INCUMBENCY_CERT`: Certificate of incumbency - `INFORMATION_STATEMENT`: Company information statement - `MEMORANDUM`: Memorandum of Association - `PARTNERSHIP_AGREEMENT`: Partnership agreement - `POWER_OF_ATTORNEY`: Power of attorney - `PROOF_OF_ADDRESS`: Utility bill, lease contract, or equivalent as proof of operational address - `PROOF_OF_NATURE_OF_BUSINESS`: Evidence describing the nature of the business - `REGULATORY_LICENSE`: Current regulatory licence - `SELF_DECLARATION_FORM`: Signed self-declaration form - `SHAREHOLDER_REGISTRY`: Shareholder registry - `SOURCE_OF_FUNDS`: Bank statements or equivalent SoF evidence - `STATE_REGISTRY`: Extract from the state business registry - `TRADE_LICENSE`: Trade licence - `TRUST_AGREEMENT`: Trust agreement - `OTHER`: Any other supporting company document - `name` string, required: Filename of the document. - `description` string: Optional description. - `countryCode` string, required: ISO 3166-1 alpha-2 country code. - `externalReference` string, uuid, required: External document tracking ID. - `content` string, required: Base64-encoded file content. Generate this by encoding the raw file bytes to base64 (PDF/JPG/PNG/etc.). - Node.js: fs.readFileSync('/path/to/file.pdf').toString('base64') - Browser: FileReader.readAsDataURL(file) and use only the part after the comma - Python: base64.b64encode(open('file.pdf','rb').read()).decode('ascii') Send the raw base64 string only (no `data:...;base64,` prefix) and without line breaks. - object: Document for individual customer - `type` 'AGREEMENT' | 'ARBITRARY_DOC' | 'BANK_CARD' | 'CONTRACT' | 'COVID_VACCINATION_FORM' | 'DRIVERS' | 'DRIVERS_TRANSLATION' | 'FILE_ATTACHMENT' | 'ID_CARD' | 'ID_DOC_PHOTO' | 'INCOME_SOURCE' | 'INVESTOR_DOC' | 'OTHER' | 'PASSPORT' | 'PAYMENT_SOURCE' | 'PROFILE_IMAGE' | 'RESIDENCE_PERMIT' | 'SELFIE' | 'UTILITY_BILL' | 'UTILITY_BILL2' | 'VEHICLE_REGISTRATION_CERTIFICATE' | 'VIDEO_SELFIE', required: Document type: - `AGREEMENT`: Signed agreement - `ARBITRARY_DOC`: Arbitrary supporting document not covered by the other types - `BANK_CARD`: Photo of a bank card - `BANK_STATEMENT`: Proof of address: bank document (bank statement, bank letter, mortgage payment document, or passbook) - `CONTRACT`: Signed contract - `COVID_VACCINATION_FORM`: COVID-19 vaccination form - `DRIVERS`: Driver's licence (two-sided: submit `FRONT_SIDE` then `BACK_SIDE`) - `DRIVERS_TRANSLATION`: Certified translation of a driver's licence - `FILE_ATTACHMENT`: Generic file attachment - `ID_CARD`: National ID card (two-sided: submit `FRONT_SIDE` then `BACK_SIDE`) - `ID_DOC_PHOTO`: Additional photo of an identity document - `INCOME_SOURCE`: Evidence of source of income (payslips, tax returns, or equivalent) - `INVESTOR_DOC`: Investor-related documentation - `OTHER`: Any other supporting document - `PASSPORT`: Passport (single-sided) - `PAYMENT_SOURCE`: Evidence of source of funds for a specific payment - `PROFILE_IMAGE`: Profile image of the individual - `RESIDENCE_PERMIT`: Residence permit (two-sided: submit `FRONT_SIDE` then `BACK_SIDE`) - `SELFIE`: Biometric selfie/liveness; must accompany every identity submission - `UTILITY_BILL`: Proof of address: utility provider document (electricity, water, gas, heating, sewerage, home phone, internet, or TV bill) - `UTILITY_BILL2`: Additional utility bill for proof of address - `VEHICLE_REGISTRATION_CERTIFICATE`: Vehicle registration certificate - `VIDEO_SELFIE`: Biometric video selfie/liveness recording - `subType` 'FRONT_SIDE' | 'BACK_SIDE': Subtype of document. Required when uploading two-sided documents such as `ID_CARD`, `DRIVERS`, or `RESIDENCE_PERMIT`. Always upload `FRONT_SIDE` before `BACK_SIDE`. Not required for `PASSPORT` (single-sided). - `name` string, required: Filename of the document. - `description` string: Optional description. - `countryCode` string, required: ISO 3166-1 alpha-2 country code. - `externalReference` string, uuid, required: External document tracking ID. - `content` string, required: Base64-encoded file content. Generate this by encoding the raw file bytes to base64 (PDF/JPG/PNG/etc.). - Node.js: fs.readFileSync('/path/to/file.pdf').toString('base64') - Browser: FileReader.readAsDataURL(file) and use only the part after the comma - Python: base64.b64encode(open('file.pdf','rb').read()).decode('ascii') Send the raw base64 string only (no `data:...;base64,` prefix) and without line breaks. ## Response `202` Documents accepted and queued for upload. - object - `reference` string, uuid: Unique reference for the document upload request. - `externalReference` string, uuid: External reference sent in the request. - `status` 'INIT': Initial status of the document upload. ## Other responses - `400`: Bad request — missing or invalid data. ## Changes - **2026-06-16** `97d6c0d2fe2e`: 4 breaking, 47 info - request property `items/anyOf[subschema #1: Business Customer Document]/subType` was restricted to a list of enum values - request property `items/anyOf[subschema #1: Business Customer Document]/type` was restricted to a list of enum values - request property `items/anyOf[subschema #2: Individual Customer Document]/subType` was restricted to a list of enum values - request property `items/anyOf[subschema #2: Individual Customer Document]/type` was restricted to a list of enum values - …47 more [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/platform/v1/customers/:customerReference/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)