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

  - `limit` (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":{"_in":[5,6,7,8]}}]}

  - `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.firstName` (string)
    Example: "Allen"

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

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

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

  - `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"