BVbvnk
Manage Documents

Upload customer documents

Changed on

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, 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.

post/platform/v2/customers/{customerId}/documents

Request

Path parameters

customerIdstring uuid required
Example:0a184641-30e2-4414-871f-3db1c683900e

Customer id.

Request body multipart/form-data

filesstring[] required

One file per metadata entry, in matching order.

Example request

{
  "metadata": [
    {
      "type": "CERTIFICATE_OF_INCORPORATION",
      "filename": "certificate.pdf",
      "description": "Certificate of Incorporation",
      "subType": "FRONT_SIDE",
      "countryCode": "DE"
    }
  ]
}

Response

Documents accepted for processing

idstring uuid

Batch correlation id for tracing; not a persistent lookup key.

customerIdstring uuid
totalDocumentsinteger
successCountinteger
failureCountinteger
createdAtstring date-time

Changes

  • c386d436bf2cRevision changes
    • breaking

      removed the enum value AML_POLICY of the request property //

    • breaking

      removed the enum value PROOF_OF_REGULATORY_LICENSE of the request property //

    • breaking

      removed the enum value SHAREHOLDER_OWNERSHIP of the request property //

    • info

      api operation id uploadCustomerCompanyDocumentsV2 removed and replaced with uploadCustomerDocumentsV2

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new BANK_STATEMENT enum value to the request property //

    • info

      added the new COMPANY_DOC enum value to the request property //

    • info

      added the new COMPANY_SOURCE_OF_WEALTH enum value to the request property //

    • info

      added the new DIRECTOR_ADDRESS_VERIFICATION enum value to the request property //

    • info

      added the new OTHER enum value to the request property //

    • info

      added the new POWER_OF_ATTORNEY enum value to the request property //

    • info

      added the new PROOF_OF_FUNDS_SAVINGS enum value to the request property //

    • info

      added the new PROOF_OF_PROFESSIONAL_ACTIVITY enum value to the request property //

    • info

      added the new PROOF_OF_RESIDENTIAL_ADDRESS enum value to the request property //

    • info

      added the new TRANSPARENCY_REGISTRY_EXTRACT enum value to the request property //

    • info

      added the new UBO_ADDRESS_VERIFICATION enum value to the request property //

    • info

      added the new UBO_SOURCE_OF_WEALTH enum value to the request property //

    • info

      added the non-success response with the status

  • 97d6c0d2fe2eRevision changes
    • info

      endpoint added