Add Documents to Customers

Add documents to a company EPC

Use the following endpoints to attach documents to an existing customer: at the company level or for a specific associate (beneficial owner, director, or signer). Each request can upload multiple documents simultaneously.

Important

• 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.**
• Files must be base64-encoded before sending.

To add documents to a company customer profile, send the POST customers/{customerReference}/documents request with 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..."
    }
]

Path Parameter

Request Body Parameters

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

Add documents to an individual EPC

Use these endpoints to attach documents to an Individual customer's profile. Each request uploads multiple documents simultaneously.

Important

• Reference the correct customerReference.
• Files must be base64-encoded before sending.

To add documents to an Individual customer profile, send the POST customers/{customerReference}/documents request with the following request body:

[
    {
        "type": "PASSPORT",
        "subType": "FRONT_SIDE",
        "name": "John Smith Passport.pdf",
        "description": "Document optional description",
        "countryCode": "GB",
        "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
        "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
    }
]

Path Parameter

Request Body Parameters

Response

Success Example:

{
  "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 status 204 No Content, which means the document is deleted.

Complete onboarding

Once you have uploaded all required documentation for an Embedded Partner Customer (EPC), confirm the completion of the onboarding process.

For that, send the POST /customers/{reference}/complete-onboardingrequest 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/{reference} request.
• Portal: Track progress and statuses directly through the BVNK Portal.
• Webhooks: Set up webhooks to receive automated updates on status changes.