# List engagements

Project engagement tracking with comprehensive workflow management

This endpoint delivers complete project engagement management including:
- Client engagement tracking with date-based filtering
- Multi-level staff assignment management (partner and manager roles)
- Project status workflow tracking and reporting
- Template-driven engagement naming and standardization
- Date range analysis for project timeline management

Project Management Capabilities:
- Start and end date tracking for project lifecycles
- Status-based workflow management (ACTIVE, COMPLETED, ON_HOLD, EXECUTED, etc.)
- Staff assignment tracking at partner and manager levels
- Client relationship management for engagement context

Workflow Features:
- Template-based engagement creation for consistency
- Status progression tracking for project milestones
- Staff allocation and responsibility assignment
- Client-specific engagement history and analysis

Business Intelligence:
- Engagement duration analysis and reporting
- Staff utilization and assignment tracking
- Client engagement patterns and history
- Project status distribution and workflow analysis

Filtering and Analysis:
- Client-specific engagement retrieval
- Status-based workflow filtering
- Date range queries for period analysis
- Staff assignment reporting and allocation

Real Example:
bash
curl --location 'https://{{host}}/v1/engagements' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'

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

## Request fields (application/json):

  - `pageSize` (integer)
    Maximum number of engagement records to return
    Example: 25

  - `page` (integer)
    Page number for pagination (0-based)

  - `clientId` (integer)
    Filter engagements by specific client ID
    Example: 420

  - `status` (string)
    Filter by engagement status
    Enum: "ACTIVE", "COMPLETED", "ON_HOLD", "EXECUTED", "CANCELLED", "PLANNED"

  - `startDate` (string)
    Start date for engagement date range filter
    Example: "2023-06-29"

  - `endDate` (string)
    End date for engagement date range filter
    Example: "2023-06-29"

  - `sortOrder` (string)
    Sort order for engagement dates
    Enum: "asc", "desc"

## Response 200 fields (application/json):

  - `deid_engagement` (array)

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

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

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

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

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

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

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

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

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

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

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

  - `deid_engagement.client` (object,null)
    Associated client details

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

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

  - `deid_engagement.client.number` (string)
    Example: "52150"

  - `deid_engagement.partnerStaff` (object,null)
    Partner staff member details

  - `deid_engagement.partnerStaff.firstName` (string)
    Example: "Robert"

  - `deid_engagement.partnerStaff.lastName` (string)
    Example: "Johnson"

  - `deid_engagement.partnerStaff.email` (string)
    Example: "r.johnson@company.com"

  - `deid_engagement.managerStaff` (object,null)
    Manager staff member details

  - `deid_engagement_aggregate` (object)

  - `deid_engagement_aggregate.aggregate` (object)

  - `deid_engagement_aggregate.aggregate.count` (integer)
    Total number of engagement records matching criteria
    Example: 1

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