> ## Documentation Index
> Fetch the complete documentation index at: https://dev.ownright.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Searching engagements

> How to filter, sort, search, and paginate through your engagements

The `engagements` query provides a powerful way to list and search through all of your
engagements. It supports filtering, text search, sorting, and cursor-based pagination.

## Basic paginated list

To retrieve a simple paginated list of engagements, use the `first` argument to specify
how many results you want:

```graphql theme={null}
query ListEngagements {
  engagements(first: 10) {
    edges {
      cursor
      node {
        ... on PurchaseEngagement {
          id
          shortId
          type
          closingDate
          owner
          status {
            state
          }
        }
        ... on RefinanceEngagement {
          id
          shortId
          type
          closingDate
          owner
          status {
            state
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Filtering

Use the `filters` argument with an `EngagementSearchFilterInput` to narrow down results.
All filter fields are optional and can be combined:

### By status

```graphql theme={null}
query ActiveEngagements {
  engagements(
    first: 20
    filters: { statuses: [RECEIVED, SETTING_UP, PREPARING_FOR_CLOSING] }
  ) {
    edges {
      node {
        ... on PurchaseEngagement {
          id
          shortId
          type
        }
        ... on RefinanceEngagement {
          id
          shortId
          type
        }
      }
    }
  }
}
```

### By type

```graphql theme={null}
query PurchaseEngagementsOnly {
  engagements(first: 20, filters: { types: [PURCHASE] }) {
    edges {
      node {
        ... on PurchaseEngagement {
          id
          shortId
          closingDate
        }
      }
    }
  }
}
```

### By province

```graphql theme={null}
query OntarioEngagements {
  engagements(first: 20, filters: { provinces: [ONTARIO, BRITISH_COLUMBIA] }) {
    edges {
      node {
        ... on PurchaseEngagement {
          id
          shortId
        }
        ... on RefinanceEngagement {
          id
          shortId
        }
      }
    }
  }
}
```

### By date range

Both `closingDate` and `createdAt` support date range filtering:

```graphql theme={null}
query EngagementsClosingThisMonth {
  engagements(
    first: 20
    filters: { closingDate: { startDate: "2025-09-01", endDate: "2025-09-30" } }
  ) {
    edges {
      node {
        ... on PurchaseEngagement {
          id
          shortId
          closingDate
        }
        ... on RefinanceEngagement {
          id
          shortId
          closingDate
        }
      }
    }
  }
}
```

### Combining filters

All filter fields can be used together. When multiple filters are specified, results must
match all of them:

```graphql theme={null}
query FilteredEngagements {
  engagements(
    first: 20
    filters: {
      types: [PURCHASE]
      statuses: [PREPARING_FOR_CLOSING, CLOSING_IN_PROGRESS]
      provinces: [ONTARIO]
      closingDate: { startDate: "2025-09-01", endDate: "2025-12-31" }
    }
  ) {
    edges {
      node {
        ... on PurchaseEngagement {
          id
          shortId
          closingDate
          owner
        }
      }
    }
  }
}
```

## Text search

Use the `query` parameter to perform a text search across engagements. This is useful
for finding engagements by client name, short ID, or other searchable fields:

```graphql theme={null}
query SearchEngagements {
  engagements(first: 10, query: "Jane Doe") {
    edges {
      node {
        ... on PurchaseEngagement {
          id
          shortId
          clients {
            firstName
            lastName
          }
        }
        ... on RefinanceEngagement {
          id
          shortId
          clients {
            firstName
            lastName
          }
        }
      }
    }
  }
}
```

<Info>
  The `query` and `filters` parameters can be combined to perform a text search
  within a filtered set of results.
</Info>

## Sorting

Control the order of results with the `sortOrder` argument using the
`EngagementSearchSortOrder` enum:

| Sort order          | Description                     |
| ------------------- | ------------------------------- |
| `CLOSING_DATE_ASC`  | Closing date, earliest first    |
| `CLOSING_DATE_DESC` | Closing date, most recent first |
| `CREATED_AT_ASC`    | Creation date, oldest first     |
| `CREATED_AT_DESC`   | Creation date, newest first     |

```graphql theme={null}
query EngagementsByClosingDate {
  engagements(first: 20, sortOrder: CLOSING_DATE_ASC) {
    edges {
      node {
        ... on PurchaseEngagement {
          id
          shortId
          closingDate
        }
        ... on RefinanceEngagement {
          id
          shortId
          closingDate
        }
      }
    }
  }
}
```

## Pagination

The `engagements` query uses cursor-based pagination. Use `pageInfo` to determine if
there are more results, and pass the `endCursor` value as the `after` argument to
fetch the next page:

```graphql theme={null}
query NextPage {
  engagements(first: 10, after: "eyJpZCI6MTB9") {
    edges {
      cursor
      node {
        ... on PurchaseEngagement {
          id
          shortId
        }
        ... on RefinanceEngagement {
          id
          shortId
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

A typical pagination loop:

<Steps>
  <Step title="Fetch the first page">
    Call `engagements(first: 20)` without an `after` cursor.
  </Step>

  <Step title="Check for more results">
    If `pageInfo.hasNextPage` is `true`, there are more results to fetch.
  </Step>

  <Step title="Fetch subsequent pages">
    Pass `pageInfo.endCursor` as the `after` argument in the next request.
    Repeat until `hasNextPage` is `false`.
  </Step>
</Steps>

<Info>
  For more details on cursor-based pagination patterns, see the
  [Pagination](/fundamentals/pagination) documentation.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Fetching engagement details" icon="file-lines" href="/lender-api/guides/fetching-engagement-details">
    Retrieve detailed information about a specific engagement.
  </Card>

  <Card title="Cancelling an engagement" icon="ban" href="/lender-api/guides/cancelling-an-engagement">
    Learn how to cancel an engagement that is no longer needed.
  </Card>
</CardGroup>