---
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-19** `55dc3fc30633` — 3 breaking, 15 info
  - the response's body type/format changed from ``/`` to `object`/`` for status `400`
  - the response's body type/format changed from ``/`` to `object`/`` for status `401`
  - the response's body type/format changed from ``/`` to `object`/`` for status `500`
  - removed `#/components/schemas/Error400_INVALID_INPUT, #/components/schemas/Error400_MISSING_MANDATORY_USER_INFO, #/components/schemas/Error400_INVITATION_ALREADY_CLAIMED, #/components/schemas/Error400_INVITATIONS_NOT_CONFIGURED, #/components/schemas/Error400_INVALID_UMA_ADDRESS, #/components/schemas/Error400_INVITATION_CANCELLED, #/components/schemas/Error400_QUOTE_REQUEST_FAILED, #/components/schemas/Error400_INVALID_PAYREQ_RESPONSE, #/components/schemas/Error400_INVALID_RECEIVER, #/components/schemas/Error400_PARSE_PAYREQ_RESPONSE_ERROR, #/components/schemas/Error400_CERT_CHAIN_INVALID, #/components/schemas/Error400_CERT_CHAIN_EXPIRED, #/components/schemas/Error400_INVALID_PUBKEY_FORMAT, #/components/schemas/Error400_MISSING_REQUIRED_UMA_PARAMETERS, #/components/schemas/Error400_SENDER_NOT_ACCEPTED, #/components/schemas/Error400_AMOUNT_OUT_OF_RANGE, #/components/schemas/Error400_INVALID_CURRENCY, #/components/schemas/Error400_INVALID_TIMESTAMP, #/components/schemas/Error400_INVALID_NONCE, #/components/schemas/Error400_INVALID_REQUEST_FORMAT, #/components/schemas/Error400_INVALID_BANK_ACCOUNT, #/components/schemas/Error400_SELF_PAYMENT, #/components/schemas/Error400_LOOKUP_REQUEST_FAILED, #/components/schemas/Error400_PARSE_LNURLP_RESPONSE_ERROR, #/components/schemas/Error400_INVALID_AMOUNT, #/components/schemas/Error400_WEBHOOK_ENDPOINT_NOT_SET, #/components/schemas/Error400_WEBHOOK_DELIVERY_ERROR` from the response body `oneOf` list for the response status `400`
  - …14 more
- …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/55dc3fc30633/schema)