> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC for Individual Customers

> Onboard individual customers with KYC identity verification. Choose API or hosted link, with Sphere-Managed or Platform-Managed compliance.

KYC (Know Your Customer) is a legal identity verification process required before any individual customer can send or receive funds through SpherePay. It is mandated by anti-money laundering (AML) regulations and must be completed once per customer. You choose how to integrate — via API or hosted link — and which compliance model to use.

## Required information

SpherePay requires the following information to verify an individual customer's identity. Fields marked as **API** are submitted in the customer creation request; fields marked as **ID Document** are extracted automatically from the uploaded document.

| Field                         | Source      | Notes                                                                          |
| ----------------------------- | ----------- | ------------------------------------------------------------------------------ |
| Email address                 | API         | `email` field in the customer creation request                                 |
| Phone number                  | API         | `phone` field in the customer creation request                                 |
| Country of residence          | API         | `address.country` in the customer creation request                             |
| Residential address           | API         | Full `address` object (street, city, postal code, state)                       |
| Tax identification number     | API         | `personalInformation.taxIdentificationNumber` — accepted types vary by country |
| First name & last name        | ID Document | Auto-extracted from the uploaded government-issued ID                          |
| Date of birth                 | ID Document | Auto-extracted from the uploaded government-issued ID                          |
| Government-issued ID document | ID Document | Uploaded via `POST /v2/document` — passport, ID card, or driver's license      |
| Proof of address              | ID Document | Uploaded via `POST /v2/document`                                               |

<Note>
  In certain circumstances SpherePay may request additional information, such as for politically exposed persons (PEPs), elderly customers, high-risk profiles, or customers with unusually high expected transaction volumes. SpherePay will contact you directly when this applies.
</Note>

## KYC flow overview

The flow below shows the steps required for individual KYC. The only step that differs between onboarding models is TOS acceptance — it is handled in-flow in Sphere-Managed and embedded in your platform's terms in Platform-Managed.

<Tabs>
  <Tab title="Sphere-Managed (default)">
    1. Create customer with full `personalInformation` and `address`
    2. Generate TOS link → redirect customer to accept terms
    3. Upload government-issued ID document
    4. Upload proof of address document
    5. Complete face liveness verification (Sumsub SDK, in-flow)
    6. Poll `GET /v2/customer/{id}` until `status` reaches `approved`
  </Tab>

  <Tab title="Platform-Managed (opt-in)">
    1. Create customer with full `personalInformation` and `address`
    2. Upload government-issued ID document
    3. Upload proof of address document
    4. Upload liveness report document from your KYC provider
    5. Poll `GET /v2/customer/{id}` until `status` reaches `approved`
  </Tab>
</Tabs>

## Choose an integration method

<Warning>
  You must pick a single integration method and onboarding model for each customer. Mixing methods for the same customer — or falling back to one if the other fails — is not supported and will result in an unsuccessful onboarding.
</Warning>

<CardGroup cols={3}>
  <Card title="KYC via API — Sphere-Managed" icon="code" href="/concepts/onboarding/individual-kyc#kyc-via-api-sphere-managed">
    Default model. Sphere handles TOS, face liveness, and OTP via hosted links.
  </Card>

  <Card title="KYC via API — Platform-Managed" icon="server" href="/concepts/onboarding/individual-kyc#kyc-via-api-platform-managed">
    Opt-in model. Upload a liveness report document. No hosted redirects required.
  </Card>

  <Card title="KYC via hosted link" icon="link" href="/concepts/onboarding/kyc-via-link">
    Fastest integration. SpherePay hosts the entire verification experience.
  </Card>
</CardGroup>

***

## KYC via API — Sphere-Managed

This is the default model for all new API integrations. Sphere handles compliance steps in-flow using hosted links and redirects: Terms of Service acceptance, face liveness verification, and OTP contact verification.

**Before you begin**, ensure you have:

* A SpherePay API key
* The customer's personal information (full address, tax ID)
* A copy of the customer's government-issued identity document

<Steps>
  <Step title="Create a customer">
    Call `POST /v2/customer` with `type: "individual"` and include the full `personalInformation` and `address` objects. These fields allow SpherePay to verify the customer's identity programmatically.

    ```json theme={"dark"}
    {
      "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"
      }
    }
    ```

    The `personalInformation` object accepts the following fields:

    | Field                                | Description                                                           |
    | ------------------------------------ | --------------------------------------------------------------------- |
    | `taxIdentificationNumberCountry`     | The customer's country code (e.g. `USA`, `SGP`, `GBR`)                |
    | `taxIdentificationNumberType`        | The ID number type, e.g. `ssn` (USA), `nric` (Singapore), `nino` (UK) |
    | `taxIdentificationNumber`            | The actual identification number                                      |
    | `taxIdentificationNumberDescription` | Human-readable description — only required when type is `other`       |
  </Step>

  <Step title="Accept Terms of Service">
    Generate a TOS link and redirect the customer to accept the Terms and Conditions and Privacy Policy.

    ```bash theme={"dark"}
    POST https://api.spherepay.co/v2/customer/{id}/tos-link
    ```

    This step can be done in parallel with uploading documents.
  </Step>

  <Step title="Upload ID document">
    Upload the customer's government-issued identity document using `POST /v2/document`.

    ```bash theme={"dark"}
    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"'
    ```

    Upload both the front and back for ID cards and driver's licenses. Passports require front only (with country-specific exceptions). See the Document Guideline for accepted formats by country.
  </Step>

  <Step title="Complete face liveness verification">
    Check the customer's `required` array via `GET /v2/customer/{id}`. Then perform **exactly one** of the following, depending on what appears in `required`:

    * **`liveness_check` in required** — Generate a face verification link via `POST /v2/enhanced-due-diligence/face-verification-link` and redirect the customer to complete an interactive liveness check via the Sumsub SDK.
    * **`liveness_report_document` in required** — Upload a liveness report document from your identity verification provider via `POST /v2/document` with `documentType: "liveness_report"`.

    <Warning>
      Do not perform both paths. Check the `required` array and follow only the matching option.
    </Warning>
  </Step>

  <Step title="Poll for verification result">
    Once all required steps are complete, SpherePay processes the verification automatically — no submit call is needed. Poll `GET /v2/customer/{id}` until `status` in `verificationProfiles` reaches `approved`.

    ```bash theme={"dark"}
    GET https://api.spherepay.co/v2/customer/{id}
    ```

    ```json theme={"dark"}
    {
      "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.
  </Step>
</Steps>

<Note>
  KYC review typically takes 0–2 business days after all required documents and data are submitted.
</Note>

***

## KYC via API — Platform-Managed

This opt-in model is for platforms that already perform KYC, collect liveness verification, and embed Sphere's Terms of Service. Your platform handles compliance upstream — no hosted redirects are required.

<Warning>
  Platform-Managed is not available by default. Your platform must meet qualification requirements and receive approval from Sphere's Compliance team before going live. Contact your dedicated Solutions Engineer to initiate the approval process.
</Warning>

**Additional prerequisites beyond the standard set:**

* A liveness report document from your identity verification provider (e.g. Sumsub, Persona)
* Platform-Managed onboarding approved for your application by Sphere Compliance

<Steps>
  <Step title="Create a customer">
    Call `POST /v2/customer` with `type: "individual"`, full `personalInformation`, and `address`. The request body is identical to the Sphere-Managed path.

    ```json theme={"dark"}
    {
      "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"
      }
    }
    ```
  </Step>

  <Step title="Upload ID document and proof of address">
    Upload the customer's identity documents via `POST /v2/document`. Repeat for each required document type.

    ```bash theme={"dark"}
    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"'
    ```
  </Step>

  <Step title="Upload liveness report">
    Upload the liveness report produced by your identity verification provider. This replaces the in-flow face liveness check used in Sphere-Managed.

    ```bash theme={"dark"}
    curl --location 'https://api.spherepay.co/v2/document' \
    --header 'Authorization: Bearer <your_api_key>' \
    --form 'target="customer"' \
    --form 'targetId="customer_4914a2f6226e42cc8d207ead9573b29f"' \
    --form 'documentType="liveness_report"' \
    --form 'file=@"/path/to/liveness_report.pdf"'
    ```

    Only upload this document if `liveness_report_document` appears in the `required` array of the customer's verification profile.
  </Step>

  <Step title="Poll for verification result">
    Once all required data and documents are submitted, SpherePay processes the KYC verification automatically. Poll `GET /v2/customer/{id}` until `status` reaches `approved`.
  </Step>
</Steps>

***

## What's next

Once the customer's verification profile is `approved`, register their payment methods and initiate a transfer.

<CardGroup cols={2}>
  <Card title="Bank accounts" icon="landmark" href="/concepts/transfers/bank-accounts">
    Register a bank account so the customer can send or receive funds via bank rail.
  </Card>

  <Card title="Wallets" icon="wallet" href="/concepts/transfers/wallets">
    Register a crypto wallet address to enable on-ramp and off-ramp transfers.
  </Card>

  <Card title="Transfers API" icon="arrow-right-left" href="/concepts/transfers/overview">
    Create and manage transfers once the customer has registered their payment methods.
  </Card>

  <Card title="Verification profile" icon="shield-check" href="/concepts/onboarding/verification-profile">
    Understand verification statuses, criteria arrays, and what triggers state changes.
  </Card>
</CardGroup>