---
title: "List Customers"
method: GET
path: "/v2/customer"
---

# List Customers

`GET /v2/customer`

List customers with optional server-side search, filters, and sort.

## Query parameters

- object, required
  - `page` string, required — Page number of the list (default: 1)
  - `limit` string, required — Number of items per page (default: 10)
  - `search` string — Substring search across customer first name, last name, legal name, trade name, and email fields
  - `email` string, email — Filter by exact customer email (individual or business)
  - `country` string — Filter by customer address country (ISO 3166-1 Alpha-3, e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries).
  - `sort` string, required — Comma-separated sort fields. Prefix with "-" for descending, "+" (or no prefix) for ascending. Allowed fields: created, updated. Example: "created,-updated".

## Response `200`

- CustomerListResponseDto
  - `customers` union[], required — Array of customer objects
    - union
      - object — Response containing information about an individual customer.
        - `id` string, required — Customer ID
        - `email` string — Customer email address
        - `phone` string — Customer phone number
        - `verificationProfiles` object[], required — Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown.
          - `name` 'kyc_profile_a' | 'kyb_profile_a' | 'ubo_kyc_profile_a' | 'kyc_profile_b' | 'kyb_profile_b' | 'kyb_profile_c' | 'kyc_profile_c' | 'ubo_kyc_profile_c', required — The name of the verification profile.
          - `status` 'incomplete' | 'pending' | 'approved' | 'rejected' | 'resubmission_required', required — The status of the verification profile.
          - `criteria` object — The criteria for the verification profile.
            - `complete` string[], required — Completed fields.
            - `pending` string[], required — Pending fields. These fields are currently being verified.
            - `required` string[], required — Required fields. These fields are required to be completed before the verification profile can be approved.
            - `errors` object[], required — The errors that occurred while verifying the fields.
              - …
        - `meta` object
        - `tosStatus` 'incomplete' | 'pending' | 'approved', required — Customer Terms of Service acceptance status (incomplete | pending | approved).
        - `createdAt` string, required — ISO 8601 formatted customer creation timestamp
        - `updatedAt` string, required — ISO 8601 formatted customer update timestamp
        - `type` 'individual', required — Customer type
        - `firstName` string — Customer first name (individual customers only)
        - `lastName` string — Customer last name (individual customers only)
        - `dateOfBirth` string — The customer's date of birth in YYYY-MM-DD format (individual customers only).
        - `personalInformation` object — Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy.
          - `taxIdentificationNumberType` string — The type of tax identification number of the customer. Required when providing tax identification information. Please refer to the [Individual Verification Criteria](/concepts/onboarding/verification-profile) for the full list of reference.
          - `taxIdentificationNumberCountry` string — The ISO3166-1 Alpha-3 country code for the tax identification number. Required when providing tax identification information. See [Country Codes](/concepts/reference/supported-countries).
          - `taxIdentificationNumberDescription` string — Description of the tax identification number. Required when type is `other`
          - `accountPurpose` 'personal_or_living_expenses' | 'payments_to_friends_or_family_abroad' | 'receive_salary' | 'receive_payment_for_freelancing' | 'protect_wealth' | 'purchase_goods_and_services' | 'charitable_donations' | 'ecommerce_retail_payments' | 'investment_purposes' | 'operating_a_company' — The purpose of the account. Required for EEA-resident individuals.
          - `gender` 'male' | 'female' | 'other' — The gender of the customer. Required by some verification providers.
          - `countryOfBirth` string — The ISO3166-1 Alpha-3 country code of the country where the customer was born. See [Country Codes](/concepts/reference/supported-countries).
          - `nationality` string — The ISO3166-1 Alpha-3 country code of the customer's nationality. Required by some verification providers. See [Country Codes](/concepts/reference/supported-countries).
          - `middleName` string — The customer's middle name. Required for some verification flows.
          - `occupationSocCode` string — The customer's occupation as a 6-digit Standard Occupational Classification (SOC) code, validated against the supported occupation list. Required for some verification flows.
          - `residencyCountry` string — The ISO3166-1 Alpha-3 country code of the customer's country of residency. Often satisfied by the address country, but some verification providers require it as a separate attribute. See [Country Codes](/concepts/reference/supported-countries).
          - `sourceOfFunds` 'salary' | 'business_income' | 'investment_returns' | 'inheritance' | 'gift' | 'savings' | 'other' — The customer's primary source of funds. Required by some verification providers.
      - object — Response containing information about a business customer.
        - `id` string, required — Customer ID
        - `email` string — Customer email address
        - `phone` string — Customer phone number
        - `verificationProfiles` object[], required — Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See [KYC Flow](/concepts/onboarding/individual-kyc) for individuals or [KYB Flow](/concepts/onboarding/business-kyb) for businesses. See [Verification Profile](/concepts/onboarding/verification-profile) for individual status definitions and criteria breakdown or [Verification Profile](/concepts/onboarding/verification-profile) for business status definitions and criteria breakdown.
          - `name` 'kyc_profile_a' | 'kyb_profile_a' | 'ubo_kyc_profile_a' | 'kyc_profile_b' | 'kyb_profile_b' | 'kyb_profile_c' | 'kyc_profile_c' | 'ubo_kyc_profile_c', required — The name of the verification profile.
          - `status` 'incomplete' | 'pending' | 'approved' | 'rejected' | 'resubmission_required', required — The status of the verification profile.
          - `criteria` object — The criteria for the verification profile.
            - `complete` string[], required — Completed fields.
            - `pending` string[], required — Pending fields. These fields are currently being verified.
            - `required` string[], required — Required fields. These fields are required to be completed before the verification profile can be approved.
            - `errors` object[], required — The errors that occurred while verifying the fields.
              - …
        - `meta` object
        - `tosStatus` 'incomplete' | 'pending' | 'approved', required — Customer Terms of Service acceptance status (incomplete | pending | approved).
        - `createdAt` string, required — ISO 8601 formatted customer creation timestamp
        - `updatedAt` string, required — ISO 8601 formatted customer update timestamp
        - `type` 'business', required — Customer type
        - `businessLegalName` string — Customer business legal name (business customers only)
        - `businessTradeName` string — Customer business trade name (business customers only)
  - `pagination` object, required
    - `page` number, required — Current page number
    - `limit` number, required — Number of items per page
    - `total` number, required — Total number of items
    - `totalPages` number, required — Total number of pages
    - `hasNext` boolean, required — Whether there is a next page
    - `hasPrevious` boolean, required — Whether there is a previous page

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `422` — Unprocessable Entity - Validation Error

---

[API](https://skmtc.net/spherepay/apis/docs-spherepay-co.md) · [All operations](https://skmtc.net/spherepay/apis/docs-spherepay-co/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/spherepay/docs-spherepay-co/versions/4f3f5484aed3/schema)