Overview

As part of the KYC check, you might receive a webhook event (kyc.verification.document_required) asking for documents to be uploaded for validation. This might happen, for example, when a Beneficial Owner’s name does not match with the name in an SSN lookup.

You can upload documents by either:

• Using the upload links.
• Using the API.

The KYC response may request fewer than three documents. In this case, provide the relevant body parameters for the requested document(s) and ignore the parameters for the other documents.

After the Beneficial Owner has submitted all the required documents requested, a kyc.verification.under_review webhook event is sent, as shown in the example below.

{
    "event": "kyc.verification.under_review",
    "customer_id": "a5bcf5a8-c4e0-4025-8183-5346176ee3db",
    "occurred_at": "2021-02-02-00:50:58.484840+00:00"
}

After the necessary checks on the submitted documents have been completed, a kyc.verification.success or kyc.verification.failed webhook event is sent.

Document upload links

The Bond platform provides HTML upload links for each requested document so that you can offer your customers a seamless experience as part of the verification process. Clicking on an upload link triggers the steps that guide a Beneficial Owner through the document upload process.

Using the links to upload documents

The specific documents needed to verify an identity are indicated in the kyc.verification.documents_required webhook event. Each required document contains a secure link indicated by upload_link. The documents must be uploaded as base64-encoded strings. Each document also contains a status, which can be either submitted or required and indicates whether or not a document has been uploaded.

An example of a kyc.verification.documents_required webhook event is shown in the example below.

{
    "event": "kyc.verification.document_required",
    "customer_id": "a5bcf5a8-c4e0-4025-8183-5346176ee3db",
    "occurred_at": "2021-02-02-00:50:58.484840+00:00",
    "documents":[
      {
        "document_type": "government_id",
        "upload_link": "https://withpersona.com/verify?template-id=tmpl_111111111111111111111111&reference-id=a5bcf5a8-c4e0-4025-8183-5346176ee3db",
        "status": "required"
      },
      {
        "document_type": "proof_of_address",
        "upload_link": "https://withpersona.com/verify?template-id=tmpl_222222222222222222222222&reference-id=a5bcf5a8-c4e0-4025-8183-5346176ee3db",
        "status": "required"
      },
      {
        "document_type": "social_security_card",
        "upload_link": "https://withpersona.com/verify?template-id=tmpl_333333333333333333333333&reference-id=a5bcf5a8-c4e0-4025-8183-5346176ee3db",
        "status": "required"
      }, 
    ]
}

Document upload API

The Bond platform provides you with a document upload API which you can integrate into your app and with which you can upload requested documents to be verified.

Using the API to upload documents

Use the POST /customers/{customer_id}/verification-kyc/documents operation and provide the body parameters as detailed below.

Government ID

government_id requires the parameters as shown in the following table.

front_image and back_image array parameters:

📘

Note

back_image is only required for passport_card, permanent_resident_card, and work_permit.

Proof of address

proof_of_address requires the parameters as shown in the following table.

Social security card

social_security_card requires the parameters as shown in the following table.

For a complete specification and interactive examples, see Submit KYC supporting documents in the Bond API Reference.