Skip to main content

Add documents to customers

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

Add documents to a 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"
}
tip

Onboarding procedures are completed automatically once you provide all the required documents and meet the customer compliance requirements.

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.

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