Add Documents to Customers

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

Add documents to a company EPC

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..."
    }
]

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

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

{
  "code": "DOCUMENTS-4000",
  "status": "BAD_REQUEST",
  "message": "Invalid document content",
  "details": {
    "errors": {
      "content": [
        "Document file content is not valid base64"
      ]
    }
  }
}

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

After uploading all required documentation for an Embedded Partner Customer (EPC), 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.

When you successfully call this endpoint:

• BVNK will initiate final compliance and verification checks.
• In the sandbox environment, EPC verification is automatically approved.
• In production, if the EPC 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 EPC's verification status via:

• API: Retrieve current EPC onboarding status by sending the GET /platform/v1/customers/{customerReference} request.
• Portal: Track progress and statuses directly through the BVNK Portal.
• Webhooks: Set up webhooks to receive automated updates on status changes.