KYC via API

Introduction

To initiate the KYC process via API, include all required personal information fields in the customer creation request. Once submitted, the customer information is verified programmatically. Any required supporting documents must then be uploaded 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 Tax ID Numbers by Country.

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

Personal Information Fields

The personalInformation object contains the customer's tax identification details. The accepted values depend on the customer's country of residence:

• taxIdentificationNumberCountry — The customer's country code (e.g. USA, SGP, GBR).
• taxIdentificationNumberType — The type of identification number. Accepted values vary by country — for example, ssn for the United States, nric for Singapore, or nino for the United Kingdom.
• taxIdentificationNumber — The actual identification number.
• taxIdentificationNumberDescription — A human-readable description of the document type.

For the full list of accepted identification types and codes by country, see Tax ID Numbers by Country.

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

Email and phone OTP verification can be triggered as soon as the customer is created — it does not depend on document upload or face liveness. Complete both email and phone OTP verification before calling Submit Verification in Step 6.

To send an OTP, use the Send Verification Code endpoint. Repeat for "type": "phone".

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, use the Verify Code endpoint to confirm it. Repeat for phone.

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, you can submit the customer's information for verification. This is the last step in the onboarding process and will trigger the verification process.

Check Readiness Before Submitting

Before calling the submit endpoint, fetch the customer using the Get Customer endpoint and inspect the verificationProfiles array. Each profile contains a criteria object with the following arrays:

• complete — Requirements that have been fulfilled.

• pending — Requirements currently being processed.

• required — Requirements that still need to be fulfilled before the customer can be verified.

• errors — Any validation errors with a name and detail for each.

  GET https://api.spherepay.co/v2/customer/{id}

Example response when NOT ready — several requirements are still outstanding:

{
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "incomplete",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number"
        ],
        "pending": [],
        "required": [
          "terms_of_service",
          "email_verification",
          "phone_verification",
          "identity_document",
          "liveness_check",
          "identity_verification",
          "kyc_a_approval"
        ],
        "errors": []
      }
    }
  ]
}

Example response when READY to submit — only identity_verification and kyc_a_approval remain in required:

{
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "incomplete",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "terms_of_service",
          "email_verification",
          "phone_verification",
          "identity_document",
          "liveness_check"
        ],
        "pending": [],
        "required": [
          "identity_verification",
          "kyc_a_approval"
        ],
        "errors": []
      }
    }
  ]
}

Submit Verification

To start the verification process, use the Submit Verification endpoint.

Response Example

{
  "customerId": "customer_4914a2f6226e42cc8d207ead9573b29f"
}

Once submitted, the verification process will take approximately 1-2 business days to complete. You can check the KYC status by polling the Get Customer endpoint — when status changes to approved in the verification profile, the customer is fully onboarded.

What's Next

With the customer onboarded, register their payment methods before initiating a transfer.

Register Payment Methods

Create a Transfer

Make Routine Transfers Easier with Onramper Accounts & Offloader Wallets