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

# List Customers

`GET /v1/customers`

## Request

- Base URL: `https://hyperscale0.ai`
- URL: `https://hyperscale0.ai/v1/customers`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

List Customers as a cursor-paginated page. A person or business your company serves. Access to each Product is granted separately. Identity facts live on the linked entity; this record carries the display name, external reference, and status.

## Query parameters

- `productId` string: Hyperscale product ID
- `limit` integer: Maximum items to return (1-100). Defaults to 50 when omitted.
- `cursor` string
- `query` string
- `createdFrom` string, date-time
- `createdTo` string, date-time
- `status` 'pending' | 'active' | 'disabled' | 'erased'

## Headers

- `X-Hyperscale-Environment` 'sandbox' | 'live'

## Response `200`

Success

- CustomerListOutput
  - `items` object[], required
    - `customerId` string, required: Tenant-local customer ID
    - `tenantId` string, required: Organization tenant ID
    - `displayName` string, required
    - `entityId` string: Hyperscale entity ID
    - `entityKind` 'person' | 'organization', required
    - `entityCountry` string, required
    - `entityStatus` 'pending' | 'verified' | 'rejected' | 'disabled' | 'not_checked', required
    - `profile` union, required
      - object
        - `kind` 'person', required
        - `nationality` string, required: ISO 3166-1 alpha-2 country code
        - `dateOfBirth` string, date, required
        - `idDocument` object, required
          - `type` 'national_id' | 'resident_id' | 'passport', required
          - `number` string, required
          - `issuingCountry` string, required: ISO 3166-1 alpha-2 country code
          - `expiresOn` string, date, required
        - `phone` string, required
        - `address` object, required
          - `line1` string, required
          - `city` string, required
          - `postalCode` string, required
          - `country` string, required: ISO 3166-1 alpha-2 country code
        - `occupation` string, required
        - `sourceOfFunds` 'salary' | 'business_income' | 'investments' | 'savings' | 'inheritance' | 'other', required
        - `politicallyExposed` boolean, required
      - object
        - `kind` 'organization', required
        - `legalForm` 'llc' | 'sole_establishment' | 'joint_stock' | 'simplified_joint_stock' | 'partnership' | 'foreign_branch' | 'nonprofit' | 'other', required
        - `registrationNumber` string, required
        - `incorporatedOn` string, date, required
        - `taxNumber` string
        - `activity` string, required
        - `phone` string, required
        - `address` object, required
          - `line1` string, required
          - `city` string, required
          - `postalCode` string, required
          - `country` string, required: ISO 3166-1 alpha-2 country code
        - `signatory` object, required
          - `fullName` string, required
          - `role` string, required
          - `idDocument` object, required
            - `type` 'national_id' | 'resident_id' | 'passport', required
            - `number` string, required
            - `issuingCountry` string, required: ISO 3166-1 alpha-2 country code
            - `expiresOn` string, date, required
        - `beneficialOwners` object[], required
          - `fullName` string, required
          - `nationality` string, required: ISO 3166-1 alpha-2 country code
          - `idDocument` object, required
            - `type` 'national_id' | 'resident_id' | 'passport', required
            - `number` string, required
            - `issuingCountry` string, required: ISO 3166-1 alpha-2 country code
            - `expiresOn` string, date, required
          - `ownershipPercent` number, required
    - `profileStatus` 'missing' | 'complete', required
    - `identity` 'test' | 'pending' | 'verified' | 'rejected' | 'disabled', required
    - `principalId` string, required: Hyperscale principal ID
    - `externalReference` string, nullable
    - `status` 'pending' | 'active' | 'disabled' | 'erased'
    - `createdAt` string, date-time
  - `nextCursor` string
  - `statusCounts` object

## Other responses

- `default`: ErrorResponse. See x-error-codes and x-errors for codes, HTTP statuses and retry guidance.

---

[API](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api.md) · [All operations](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/revisions/e9e8faa044d5?raw)