---
title: "List customers"
method: GET
path: "/customers"
tags: ["Customers"]
---

# List customers

`GET /customers`

Retrieve a list of customers with optional filtering parameters. Returns all customers that match
the specified filters. If no filters are provided, returns all customers (paginated).

## Query parameters

- `platformCustomerId` string
- `customerType` 'INDIVIDUAL' | 'BUSINESS' — Whether the customer is an individual or a business entity
- `createdAfter` string, date-time
- `createdBefore` string, date-time
- `updatedAfter` string, date-time
- `updatedBefore` string, date-time
- `limit` integer
- `cursor` string
- `umaAddress` string
- `isIncludingDeleted` boolean

## Response `200`

Successful operation

- object
  - `data` CustomerOneOf[], required — List of customers matching the filter criteria
    - union
      - IndividualCustomer
        - `id` string — System-generated unique identifier
        - `platformCustomerId` string, required — Platform-specific customer identifier
        - `kycStatus` 'APPROVED' | 'REJECTED' | 'PENDING_REVIEW' | 'EXPIRED' | 'CANCELED' | 'MANUALLY_APPROVED' | 'MANUALLY_REJECTED' — The current KYC status of a customer
        - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
        - `createdAt` string, date-time — Creation timestamp
        - `updatedAt` string, date-time — Last update timestamp
        - `isDeleted` boolean — Whether the customer is marked as deleted
        - `customerType` 'INDIVIDUAL', required
        - `fullName` string — Individual's full name
        - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
        - `nationality` string — Country code (ISO 3166-1 alpha-2)
        - `address` Address
          - `line1` string, required — Street address line 1
          - `line2` string — Street address line 2
          - `city` string — City
          - `state` string — State/Province/Region
          - `postalCode` string, required — Postal/ZIP code
          - `country` string, required — Country code (ISO 3166-1 alpha-2)
      - BusinessCustomer
        - `id` string — System-generated unique identifier
        - `platformCustomerId` string, required — Platform-specific customer identifier
        - `kycStatus` 'APPROVED' | 'REJECTED' | 'PENDING_REVIEW' | 'EXPIRED' | 'CANCELED' | 'MANUALLY_APPROVED' | 'MANUALLY_REJECTED' — The current KYC status of a customer
        - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
        - `createdAt` string, date-time — Creation timestamp
        - `updatedAt` string, date-time — Last update timestamp
        - `isDeleted` boolean — Whether the customer is marked as deleted
        - `customerType` 'BUSINESS', required
        - `address` Address
          - `line1` string, required — Street address line 1
          - `line2` string — Street address line 2
          - `city` string — City
          - `state` string — State/Province/Region
          - `postalCode` string, required — Postal/ZIP code
          - `country` string, required — Country code (ISO 3166-1 alpha-2)
        - `businessInfo` object — Additional information required for business entities
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
        - `beneficialOwners` UltimateBeneficialOwner[]
          - `fullName` string, required — Individual's full name
          - `emailAddress` string, email — Email address of the individual
          - `phoneNumber` string — Phone number of the individual in E.164 format
          - `taxId` string — Tax identification number of the individual. This could be a Social Security Number (SSN) for US individuals, Tax Identification Number (TIN) for non-US individuals, or a Passport Number.
          - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string — Country code (ISO 3166-1 alpha-2)
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `individualType` 'DIRECTOR' | 'CONTROL_PERSON' | 'BUSINESS_POINT_OF_CONTACT' | 'TRUSTEE' | 'SETTLOR' | 'GENERAL_PARTNER', required — Type of individual in the corporation
          - `percentageOwnership` number — Percent of ownership when individual type is beneficial owner
          - `title` string — Title at company
  - `hasMore` boolean, required — Indicates if more results are available beyond this page
  - `nextCursor` string — Cursor to retrieve the next page of results (only present if hasMore is true)
  - `totalCount` integer — Total number of customers matching the criteria (excluding pagination)

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `500` — Internal service error

## Changes

- **2026-02-07** `e951665c552d` — 2 breaking, 2 info
  - removed the required property `data/items/oneOf[subschema #1: Individual Customer]/allOf[#/components/schemas/Customer]/customerType` from the response with the `200` status
  - removed the required property `data/items/oneOf[subschema #2: Business Customer]/allOf[#/components/schemas/Customer]/customerType` from the response with the `200` status
  - the response property `data/items/oneOf[subschema #1: Individual Customer]/allOf[#/components/schemas/IndividualCustomerFields]/customerType` became required for the status `200`
  - the response property `data/items/oneOf[subschema #2: Business Customer]/allOf[#/components/schemas/BusinessCustomerFields]/customerType` became required for the status `200`
- **2026-02-06** `9d1655bef82d` — 2 breaking
  - the response property `data/items/oneOf[subschema #1: Individual Customer]/allOf[#/components/schemas/IndividualCustomerFields]/customerType` became optional for the status `200`
  - the response property `data/items/oneOf[subschema #2: Business Customer]/allOf[#/components/schemas/BusinessCustomerFields]/customerType` became optional for the status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/customers/get.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/e951665c552d/schema)