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 Document Guideline.

Core Steps

The following steps are required for every KYC API integration.

1. Create a Customer

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

Request Example

{
    "type": "individual",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "address": {
      "line1": "233 South Wacker Drive",
      "line2": "Suite 4700",
      "city": "Chicago",
      "postalCode": "60606",
      "state": "IL",
      "country": "USA"
    },
    "personalInformation": {
      "taxIdentificationNumber": "123456789",
      "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. Optional — only required when taxIdentificationNumberType is other.

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

2. 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

{
  "target": "customer",
  "targetId": "customer_4914a2f6226e42cc8d207ead9573b29f",
  "documentType": "id_card",
  "fileName": "document.jpg",
  "fileSize": 2048576,
  "mimeType": "image/jpeg",
  "createdAt": "2025-05-23T11:45:00Z"
}

3. Liveness Verification

Each customer requires liveness verification. Check the customer's required array using the Get Customer endpoint to determine which path applies, then perform only one of the following.

4. Poll for Verification Result

Once all required steps are complete, SpherePay automatically processes the verification — no submit call is needed. Poll the Get Customer endpoint until status in verificationProfiles reaches approved.

Approved Response Example

{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "identity_document",
          "liveness_report_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual"
}

When required is empty and status is approved, the customer is fully onboarded and ready to transfer.

Additional Steps

The following steps are only required for some integrations. Check the required array in your customer's verification profile using the Get Customer endpoint — only perform a step if its corresponding item appears there. See the Verification Profile reference for details on each field.

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