---
title: "List Clients"
method: GET
path: "/internal/api/clients/"
tags: ["CLIENT", "Client Management"]
---

# List Clients

`GET /internal/api/clients/`

## Request

- Base URL: `https://api.signalshq.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.signalshq.io/internal/api/clients/`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Get a paginated list of clients with optional filtering and sorting.

## Query parameters

- `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE'
- `filing_type` 'INDIVIDUAL_1040' | 'SOLO_SCHEDULE_C'
- `filing_status` 'SINGLE' | 'MARRIED_FILING_JOINTLY' | 'MARRIED_FILING_SEPARATELY' | 'HEAD_OF_HOUSEHOLD' | 'QUALIFYING_SURVIVING_SPOUSE'
- `page` integer: Page number (1-based)
- `page_size` integer: Number of items per page (max 100)
- `sort_by` 'created_at' | 'name' | 'email' | 'readable_id' | 'filing_type' | 'filing_status': Client sort field enumeration
- `sort_order` 'asc' | 'desc': Sort order enumeration
- `search_query` string, nullable: Search term

## Response `200`

Successful Response

- ClientSearchResponse: Client-specific search response using generic pagination structure with meta object
  - `clients` ClientListResponse[], required: List of clients
    - `id` string, uuid, required
    - `readable_id` string, required
    - `external_id` string, nullable, required
    - `full_name` string, required
    - `filing_type` FilingTypeResponse, required: Response schema for filing type with value and human-readable label. Provides both the enum value and display-friendly text for frontend use.
      - `value` 'INDIVIDUAL_1040' | 'SOLO_SCHEDULE_C', required
      - `label` string, required: Human-readable label for the filing type
    - `filing_status` FilingStatusResponse, required: Response schema for filing status with value and human-readable label. Provides both the enum value and display-friendly text for frontend use.
      - `value` 'SINGLE' | 'MARRIED_FILING_JOINTLY' | 'MARRIED_FILING_SEPARATELY' | 'HEAD_OF_HOUSEHOLD' | 'QUALIFYING_SURVIVING_SPOUSE', required
      - `label` string, required: Human-readable label for the filing status
    - `blind` boolean, required
    - `disabled` boolean, required
    - `email` string, email, nullable, required
    - `phone` string, nullable, required
    - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE', required
    - `ssn_info` SSNInfoResponse, required: Response schema for SSN information. This schema represents encrypted SSN information that is returned to the client. The actual SSN is never returned in plain text - only masked versions are provided.
      - `id` string, uuid, required: Unique identifier for the SSN record
      - `entity_type` 'CLIENT' | 'SPOUSE' | 'DEPENDENT', required: Entity types for SSN information
      - `ssn_masked` string, required: Masked SSN showing only last 4 digits
      - `ssn_type` 'SSN' | 'ITIN', required: SSN types
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `meta` AppSchemasCommonPaginationPaginationMeta, required
    - `page` integer, required: Current page number
    - `page_size` integer, required: Number of items per page
    - `total_count` integer, required: Total number of items
    - `total_pages` integer, required: Total number of pages
    - `total` integer, required: Alias for total_count for backward compatibility

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/signalshq/apis/signals-api.md) - [All operations](https://skmtc.dev/signalshq/apis/signals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signalshq/apis/signals-api/revisions/2c22af3b5576?raw)