Skip to main content

Add documents to customers

Make sure to study Compliance Requirements before submitting the corresponding documents.

Add documents to a Company customer​

Each request can upload multiple documents simultaneously.

When uploading customer documents:
  • Reference the correct customerReference.
  • Use customerPersonReference when the document belongs to a specific associate.
  • If customerPersonReferenceis omitted or null, the document is attached at the company level for business customers.
  • Encode files to Base64 before sending.

To add documents to a customer profile, send the POST customers/{customerReference}/documents request with the customerReference in the path and the following request body:

[
    {
        "type": "COMPANY_DOC",
        "subType": "INCORPORATION_CERT",
        "name": "Company Structure.pdf",
        "description": "Document optional description",
        "countryCode": "GB",
        "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
        "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
    },
    {
        "customerPersonReference": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab",
        "type": "PASSPORT",
        "subType": "FRONT_SIDE",
        "name": "John Smith Passport.pdf",
        "description": "Document optional description",
        "countryCode": "GB",
        "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
        "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
    }
]
ParameterRequiredDescription
customerReference✅The unique identifier of the customer to whom the documents will be attached. Customer has to be in INFO_REQUIRED status (status after agreement consent)
AttributeRequiredDescription
customerPersonReference❌Reference that links the document to a specific associate (for example, beneficial owner). If omitted or null, the document is attached at the company level.
type✅The document type, for example COMPANY_DOC.
See the full list of supported COMPANY document type.
When uploading documents for an associate (e.g. ) refer to the following list for supported document types.
subType❌Additional specification of the document type, e.g. FRONT_SIDE, BACK_SIDE if applicable.
See the full list of supported document subType for COMPANY documents.
When uploading documents for an associate (e.g. PASSPORT) refer to the following list for supported document subTypes.
name✅Optional human-readable filename, for example, "John Smith Passport.pdf".
description❌Optional description for the provided document
countryCode✅ISO 3166-1 alpha-2 country code associated with the document.
externalReference✅The internal reference mapped to the document from your end.
content✅Base64-encoded file content.

In the successful response, you receive unique references for tracking the status. That means the request has been accepted and the documents are queued for upload.

{
  "reference": "d42e1c62-27b8-4b3b-b51e-eb10edeb1731",
  "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
  "status": "INIT"
}

Manage documents​

Tips
  • Check Document Status. Retrieve the customer or associated person object to confirm document verification status.
  • Retain Document References. Store the reference returned in the success response for future queries or audits.
  • Combine with KYC. Document verification may be required before the customer status changes from PENDING to VERIFIED.

Search Documents​

To search for specific documents, send the GET /platform/v1/customers/documents request with the optional query parameters:

  • customerReference
  • externalReference
  • name
  • types
  • subTypes
  • statuses (e.g., INIT, PENDING, APPROVED, DECLINED)

Get document download URL​

To get a Document Download link, send the GET /platform/v1/customers/documents/{documentReference}/url request with the {documentReference} specified in the query.

In the successful response, you receive a temporary URL for document download.

Delete document​

To remove a document from a customer's profile, send the DELETE /platform/v1/customers/documents/{documentReference} request with the {documentReference} specified in the query.

In the successful response, you receive the status 204 No Content, which means the document is deleted.

Complete onboarding​

This feature will be discontinued and deprecated after January 31, 2026.

The endpoint is no longer used in the onboarding flow. Now, onboarding procedures are completed automatically once you provide all the required documents and meet the customer compliance requirements.

After uploading all required documentation for a customer, wait ~10 seconds for the system to acknowledge the documents. Then, confirm the completion of the onboarding process.

For that, send the POST /platform/v1/customers/{customerReference}/complete-onboarding request with reference as the path parameter.

ParameterRequiredDescription
customerReference✅The unique reference identifier for the customer provided during customer creation.

When you successfully call this endpoint:

  • BVNK will initiate final compliance and verification checks.
  • In the sandbox environment, customer verification is automatically approved.
  • In production, if the customer meets all compliance requirements, the status will update to VERIFIED. If there are outstanding requirements or issues, the status will move to INFO_REQUIRED or REJECTED, prompting manual review or further actions.

Check monitoring status​

You can monitor the customer's verification status via:

What's next?

After you create and onboard your customers, you are ready to send and receive payments.

  • See the available use cases to select the one that best suits your needs.
  • Create a wallet for yourself or your customers.
  • If you are onboarding a Business customer, you also need to submit the questionnaires for them.
Last updated on