---
title: "Search Clients"
method: POST
path: "/internal/api/clients/search"
tags: ["CLIENT", "Client Management"]
---

# Search Clients

`POST /internal/api/clients/search`

## 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/search`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Search clients with filters and pagination.

## Request body

- ClientSearchRequest: Client-specific search request extending generic pagination
  - `search_query` string, nullable: Search by name, email, or readable_id
  - `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
  - `page_size` integer: Items per page
  - `sort_by` string: Sort field (created_at, name, email, readable_id, filing_type, filing_status)
  - `sort_order` string: Sort order (asc, desc)

## 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)