KYC via API — Sphere-Managed

Introduction

This guide covers the Sphere-Managed KYC integration — the default onboarding model for all new API integrations.

In this model, Sphere handles compliance steps in-flow using hosted links and redirects: Terms of Service acceptance, face liveness verification, and OTP contact verification.

KYC via API Flow — Sphere-Managed

Core Steps

The following steps are required for every Sphere-Managed KYC API integration.

1. Create a Customer

To create a customer, 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. Accept Terms of Service

Generate a Terms of Service link and redirect the customer to accept the Terms and Conditions and Privacy Policy. To generate a TOS link, use the Generate TOS Link endpoint.

Once the link is generated, redirect the customer to complete the Terms of Service acceptance. This step can be done in parallel with creating the customer.

3. Upload Required Documents

Upload the required documents for the KYC process using the Upload Document 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"
}

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

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