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

  - `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)
    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)
    Partner staff member details

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

  - `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)
    Manager staff member details

  - `deid_engagement.managerStaff.id` (integer)
    Example: 15

  - `deid_engagement.managerStaff.firstName` (string)
    Example: Sarah

  - `deid_engagement.managerStaff.lastName` (string)
    Example: Martinez

  - `deid_engagement.managerStaff.email` (string)
    Example: s.martinez@company.com

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