Uploading KYC documentation

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 customer’s name does not match with the name in an SSN lookup.

You can upload documents by either:

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 your customer 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.passed or kyc.verification.failed webhook event is sent.

Supported documents

Supported file types

.jpg, .png, .heic, .pdf

Supported document types

Government ID, Proof of address, Social security card.

Document upload links

Bond provides a fully hosted solution for uploading KYC documentation so that you can offer your customers a seamless experience as part of the verification process. In our webhook response, we provide HTTPS links that you can embed/forward your customer to that can be collected the documents safely and securely. Loading the link triggers the steps that guide a customer 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 if a document has been uploaded or not.

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

Bond also provides you with a document upload API. If you would like to control your user's experience and use your own front end to collect documents, you can integrate Bond's Document Upload API to pass along these documents to the Bond platform.

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.

Parameter

Type

Description

type
required

String

One of:
drivers_license, passport, state_id, passport_card, permanent_resident_card, work_permit, visa

country
required

String

ISO 3166-1 alpha-2 country code, maximum two characters.

front_image
required

Object

Array of file-name and image. See table below.

back_image
required

Object

Array of file-name and image. See table below.

front_image and back_image array parameters:

Parameter

Type

Description

file-name
required

String

Name of the file, freeform alphanumeric.

image
required—see note below

String

Image as a base64-encoded string, for example GVyDQobyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg==

📘

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.

Parameter

Type

Description

type
required

String

utility_bill or property_tax_bill

file-name
required

String

Name of the file, freeform alphanumeric.

image
required

String

Image as a base64-encoded string, for example GVyDQobyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg==

Social security card

social_security_card requires the parameters as shown in the following table.

Parameter

Type

Description

file-name
required

String

Name of the file, freeform alphanumeric.

image
required

String

Image as a base64-encoded string, for example GVyDQobyAxMCAwIFINCj4+DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg==

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


Did this page help you?