# Search clients

Advanced client filtering with custom GraphQL where clauses and dynamic ordering

This query provides maximum flexibility for client data retrieval through custom
GraphQL-style where clause construction and dynamic ordering specifications.
It's designed for complex business requirements that need sophisticated filtering logic.

Key Features:
- Custom GraphQL where clause construction for unlimited filtering combinations
- Dynamic order_by specifications supporting multi-field sorting with custom directions
- Advanced boolean logic combining multiple filter conditions with _and, _or, _not
- Relationship-based filtering across connected entities (contacts, staff assignments)
- Custom pagination with flexible pageSize and page controls for any result set size
- Full access to GraphQL query capabilities through REST interface abstraction
- Enterprise-grade filtering supporting complex business logic requirements
- Support for nested queries and conditional logic patterns

Advanced Filtering Capabilities:
- Boolean Logic: _and, _or, _not operators for complex condition combinations
- Text Operations: _like, _ilike, _regex for pattern matching and search
- Comparison Operators: _gt, _gte, _lt, _lte, _eq, _neq for numerical/date comparisons  
- Array Operations: _in, _nin for multi-value filtering and inclusion/exclusion
- Null Handling: _is_null for empty value detection and filtering
- Relationship Traversal: Filter on connected entities like contacts and staff
- Date Ranges: Precision timestamp filtering for time-based analysis
- Case Sensitivity: Both case-sensitive and case-insensitive text matching

Dynamic Ordering Options:
- Multi-field Sorting: Order by multiple columns with individual sort directions
- Relationship Sorting: Sort by connected entity fields (staff names, contact info)
- Custom Directions: Mix ascending and descending order across different fields
- Priority Ordering: Define primary, secondary, tertiary sort criteria
- Date-based Sorting: createdAt, updatedAt for chronological ordering
- Text Sorting: Alphabetical ordering with locale-aware collation

Real Example:
bash
curl --location 'https://{{host}}/v1/clients/search' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "name": {
              "_ilike": "%tech%"
            }
          },
          {
            "clientRef": {
              "_ilike": "%45%"
            }
          }
        ]
      },
      {
        "active": {
          "_eq": true
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "partnerStaffId": {
          "_in": [
            5,
            6,
            7,
            8
          ]
        }
      }
    ]
  },
  "orderBy": [
    {
      "name": "asc"
    },
    {
      "createdAt": "desc"
    }
  ]
}'

Endpoint: POST /gql/v1/clients/search
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `limit` (integer)
    Maximum number of filtered clients to return
    Example: 1

  - `where` (object)
    GraphQL-style where clause for complex filtering
    Example: {"_and":[{"_or":[{"name":{"_ilike":"%tech%"}},{"clientRef":{"_ilike":"%45%"}}]},{"active":{"_eq":true}},{"createdAt":{"_gte":"1900-01-01T00:00:00Z"}},{"partnerStaffId":{"_in":[5,6,7,8]}}]}

  - `orderBy` (array)
    Dynamic ordering specifications with multiple fields
    Example: [{"name":"asc"},{"createdAt":"desc"}]

## Response 200 fields (application/json):

  - `clients` (array)

  - `clients.id` (integer)
    Unique client identifier
    Example: 3001

  - `clients.pmsRef` (string)
    Practice management system reference
    Example: "1650"

  - `clients.clientRef` (string)
    Client reference number
    Example: "48250"

  - `clients.name` (string)
    Client name or company name
    Example: "TechFlow Enterprises"

  - `clients.clientKey` (string)
    Client key identifier
    Example: "000000048250                              f"

  - `clients.active` (boolean)
    Client active status
    Example: true

  - `clients.partnerStaffId` (integer)
    Partner staff member assigned to client
    Example: 6

  - `clients.managerStaffId` (integer)
    Manager staff member assigned to client
    Example: 25

  - `clients.createdAt` (string)
    Client record creation timestamp
    Example: "2024-05-12T22:43:57.189235+00:00"

  - `clients.updatedAt` (string)
    Client record last update timestamp
    Example: "2024-05-12T22:43:57.189235+00:00"

  - `clients.clientContactInfo` (object,null)
    Client contact information

  - `clients.clientContactInfo.id` (integer)
    Example: 2850

  - `clients.clientContactInfo.firstName` (string,null)
    Example: "Jennifer"

  - `clients.clientContactInfo.lastName` (string,null)
    Example: "Martinez"

  - `clients.clientContactInfo.email` (string,null)
    Example: "jennifer@techflow.com"

  - `clients.clientContactInfo.phone` (string,null)
    Example: "555-0123"

  - `clients.clientContactInfo.address` (string,null)
    Example: "123 Business Plaza"

  - `clients.clientContactInfo.city` (string,null)
    Example: "San Francisco"

  - `clients.clientContactInfo.state` (string,null)
    Example: "CA"

  - `clients.clientContactInfo.zip_code` (string,null)
    Example: "94105"

  - `clients.partnerStaff` (object)
    Partner staff member details

  - `clients.managerStaff` (object)
    Manager staff member details

  - `total` (object)

  - `total.aggregate` (object)

  - `total.aggregate.count` (integer)
    Total number of clients matching filter criteria
    Example: 59

## Response 400 fields (application/json):

  - `error` (string)

  - `code` (string)

## Response 401 fields (application/json):

  - `error` (string)

  - `code` (string)

## Response 500 fields (application/json):

  - `error` (string)

  - `code` (string)