# Search engagements

**Search Engagements with Dynamic Filters**
This endpoint allows you to search engagements using dynamic filters, enabling flexible querying based on various criteria.
**Features:**
- Supports multiple filter conditions
- Pagination for large result sets
- Sorting options for results

**Example Usage:**

```bash
curl --location 'https://{{host}}/v1/engagements/search' \
--data '{
  "pageSize": 1,
  "where": {
    "_and": [
      {
        "_or": [
          {
            "name": {
              "_ilike": "%review%"
            }
          },
          {
            "engagementNameTemplate": {
              "_ilike": "%tax%"
            }
          }
        ]
      },
      {
        "status": {
          "_in": ["ACTIVE", "EXECUTED"]
        }
      },
      {
        "createdAt": {
          "_gte": "1900-01-01T00:00:00Z"
        }
      },
      {
        "partnerStaffId": {
          "_in": [
            5,
            6,
            7,
            8
          ]
        }
      }
    ]
  },
  "orderBy": [
    {
      "name": "asc"
    },
    {
      "createdAt": "desc"
    }
  ]
}'
```

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

## Request fields (application/json):

  - `pageSize` (integer)
    Maximum number of engagements to return
    Example: 1

  - `where` (object)
    GraphQL-style where clause for complex filtering
    Example: {"_and":[{"_or":[{"name":{"_ilike":"%review%"}},{"engagementNameTemplate":{"_ilike":"%tax%"}}]},{"status":{"_in":["ACTIVE","EXECUTED"]}},{"createdAt":{"_gte":"1900-01-01T00:00:00Z"}},{"partnerStaffId"…

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

## Response 200 fields (application/json):

  - `engagements` (array)

  - `engagements.id` (integer)
    Unique engagement identifier
    Example: 8

  - `engagements.name` (string)
    Generated engagement name from template
    Example: 2024 Annual Review and Tax 52150

  - `engagements.start_dt` (string)
    Engagement start date
    Example: 2024-03-15

  - `engagements.end_dt` (string)
    Engagement end date
    Example: 2024-04-30

  - `engagements.status` (string)
    Current engagement status
    Example: EXECUTED

  - `engagements.client_id` (integer)
    Associated client identifier
    Example: 420

  - `engagements.partner_staff_id` (integer)
    Partner staff member assigned to engagement
    Example: 53

  - `engagements.manager_staff_id` (integer)
    Manager staff member assigned to engagement
    Example: 15

  - `engagements.created_at` (string)
    Engagement record creation timestamp
    Example: 2024-03-14T10:58:38.605333+00:00

  - `engagements.updated_at` (string)
    Engagement record last update timestamp
    Example: 2024-07-27T00:08:05.822177+00:00

  - `engagements.engagement_name_template` (string)
    Template used to generate engagement name
    Example: {{fiscal_year.year}} {{letter_template.name}} {{client.number}}

  - `engagements.client` (object)
    Client details with number field

  - `engagements.client.id` (integer)
    Example: 420

  - `engagements.client.name` (string)
    Example: TechFlow Enterprises

  - `engagements.client.number` (string)
    Example: 52150

  - `engagements.partnerStaff` (object)
    Staff member basic information

  - `engagements.partnerStaff.id` (integer)
    Example: 53

  - `engagements.partnerStaff.firstName` (string)
    Example: Allen

  - `engagements.partnerStaff.lastName` (string)
    Example: Hermiston

  - `engagements.partnerStaff.email` (string)
    Example: allen.hermiston@company.com

  - `totalCount` (integer)
    Total number of engagements matching the filters
    Example: 100

## Response 400 fields (application/json):

  - `error` (string, required)
    Human-readable error message
    Example: Invalid parameter value

  - `code` (string, required)
    Machine-readable error code
    Example: INVALID_PARAMETER

  - `details` (string)
    Additional error context
    Example: The 'pageSize' parameter must be between 1 and 1000

## Response 401 fields (application/json):

  - `error` (string, required)
    Human-readable error message
    Example: Invalid parameter value

  - `code` (string, required)
    Machine-readable error code
    Example: INVALID_PARAMETER

  - `details` (string)
    Additional error context
    Example: The 'pageSize' parameter must be between 1 and 1000

## Response 500 fields (application/json):

  - `error` (string, required)
    Human-readable error message
    Example: Invalid parameter value

  - `code` (string, required)
    Machine-readable error code
    Example: INVALID_PARAMETER

  - `details` (string)
    Additional error context
    Example: The 'pageSize' parameter must be between 1 and 1000