Customer KYC via API (Individual Only)

Introduction

To initiate the KYC process via API, you will need to include all the optional fields in the customer creation request. By doing so, the customer information will then be verified programmatically and need not an independent KYC link to be generated. Once the information has been sent, document upload will be required to complete the KYC process.

KYC via API Flow

The required documents for the KYC Process are:

• Identification Document

For the complete list of acceptable identification documents, please refer to the Individual Verification Criteria.

Onboarding a Customer step by step using KYC API

The following steps will guide you through the process of onboarding a customer step by step using KYC API.

1. Create a Customer

To create a customer, you can use the Create Customer endpoint.

Request Example

{
    "type": "individual",
    "email": "test@example.com",
    "phone": "+1234567890",
    "address": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "postalCode": "string",
      "state": "string",
      "country": "string"
    },
    "personalInformation": {
      "taxIdentificationNumber": "1234567890",
      "taxIdentificationNumberType": "ssn",
      "taxIdentificationNumberCountry": "USA",
      "taxIdentificationNumberDescription": "Social Security Number"
    }
  }

2. Accepting Terms of Service

After a customer has been created, you can generate a TOS link to redirect the customer to the Terms of Service and Privacy Policy. To generate a TOS link, you can use the Generate TOS Link endpoint

Once the link is generated, you can redirect the customer to the link to complete the onboarding process. The customer is expected to accept the Terms and Conditions, and Privacy Policy before proceeding.

3. Upload Required Documents

Once the customer has been created, you can upload the required documents for the KYC process. To upload the required documents, you can use the Upload Required Documents endpoint.

Request Example

curl --location 'https://api.spherepay.co/v2/document' \
--header 'Authorization: Bearer <your_api_key>' \
--form 'target="customer"' \
--form 'targetId="customer_4914a2f6226e42cc8d207ead9573b29f"' \
--form 'documentType="id_card"' \
--form 'side="front"' \
--form 'file=@"/path/to/your/document.jpg"' \
--form 'country="SGP"'

Response Example

{
  "id": "document_4914a2f6226e42cc8d207ead9573b29f",
  "target": "customer",
  "targetId": "customer_4914a2f6226e42cc8d207ead9573b29f",
  "documentType": "id_card",
  "description": "John Doe passport for identity verification",
  "fileName": "id_card_john_doe.jpg",
  "fileSize": 2048576,
  "mimeType": "image/jpeg",
  "createdAt": "2025-05-23T11:45:00Z"
}

4. Face Liveness Verification

Once the required documents have been uploaded, you can request for face liveness verification. To request for face liveness verification, you can use the Request Face Liveness Verification endpoint.

Response Example

{
  "url": "<https://sumsub.com/websdk/p/sbx_12345678-abcd-efgh-ijkl-123456789012>",
  "expiresAt": "2025-05-23T23:59:59Z"
}

Once the link is generated, you can redirect the customer to the link to complete the face liveness verification process. The customer is expected to complete the face liveness verification process before proceeding.

5. Email and Phone verification

To verify the customer's email and phone number, you can use the Verify Email and Phone endpoint.

Request Example

{
  "type": "email"
}

Response Example

{
  "customerId": "customer_4914a2f6226e42cc8d207ead9573b29f",
  "expiresAt": "2025-05-23T23:59:59Z"
}

Once the integrator has collected the otp code from the customer, they can use the Verify Email and Phone endpoint to verify the customer's email and phone number.

Request Example

{
  "type": "email",
  "code": "123456"
}

Response Example

{
  "customerId": "customer_4914a2f6226e42cc8d207ead9573b29f",
  "verifiedAt": "2025-05-23T23:59:59Z"
}

6. Submit Verification

Once all the steps above have been completed, including the face liveness verification and the customer's email and phone number have been verified, you can proceed to submit the customer's information for verification. To start the verification process, you can use the Submit Verification endpoint. This is the last step in the onboarding process and will trigger the verification process.

Response Example

{
  "customerId": "customer_4914a2f6226e42cc8d207ead9573b29f",
}

Please note that the HTTP status code for this endpoint is 200 OK. Once the verification is submitted, the customer will be onboarded and subject for further verification. The process will take approximately 1-2 business days to complete. You can check the KYC status to ensure the customer has completed the KYC process by checking the Get Customer endpoint.

7. Register Bank Account

Once the customer has been created and the KYC/KYB process is complete, you can register a bank account for the customer. Please refer to the Register Bank Account guide for more information.

8. Create a Transfer

Once the customer has been created and the KYC/KYB process is complete, you can create a transfer for the customer. Please refer to the Transfer guide for more information.