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

# Engagements

> Search and list engagements.

<RequestExample>
  ```graphql Request [expandable] theme={null}
  query GetEngagements($after: String, $before: String, $filters: EngagementSearchFilterInput, $first: Int, $last: Int, $query: String, $sortOrder: EngagementSearchSortOrder) {
    engagements(after: $after, before: $before, filters: $filters, first: $first, last: $last, query: $query, sortOrder: $sortOrder) {
      nodes {
        cancellable
        createdAt
        id
        owner
        shortId
        type
        clients {
          email
          firstName
          lastName
          middleName
          phoneNumber
        }
        ... on PurchaseEngagement {
          closingDate
          property {
            address {
              city
              country
              latitude
              longitude
              postalCode
              province
              shortTitle
              street
              title
              unitNumber
            }
          }
          status {
            state
          }
        }
        ... on RefinanceEngagement {
          closingDate
          property {
            address {
              city
              country
              latitude
              longitude
              postalCode
              province
              shortTitle
              street
              title
              unitNumber
            }
          }
          status {
            state
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
  ```

  ```graphql Variables theme={null}
  {
    "after": "example-after",
    "before": "example-before",
    "filters": {
      "closingDate": {
        "endDate": "2025-06-15",
        "startDate": "2025-06-15"
      },
      "createdAt": {
        "endDate": "2025-06-15",
        "startDate": "2025-06-15"
      },
      "provinces": [
        "ALBERTA"
      ],
      "statuses": [
        "CANCELLED"
      ],
      "types": [
        "PURCHASE"
      ]
    },
    "first": 10,
    "last": 10,
    "query": "search term",
    "sortOrder": "CLOSING_DATE_ASC"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "engagements": {
        "nodes": [
          {
            "cancellable": true,
            "createdAt": "2025-01-15T10:30:00Z",
            "id": "gid://ownright/Engagement/1",
            "owner": "Jane Doe",
            "shortId": "ABC-123",
            "type": "PURCHASE",
            "clients": [
              {
                "email": "jane@example.com",
                "firstName": "Jane",
                "lastName": "Doe",
                "middleName": "M",
                "phoneNumber": "+14165551234"
              }
            ],
            "closingDate": "2025-06-15",
            "property": {
              "address": {
                "city": "Toronto",
                "country": "CANADA",
                "latitude": 1,
                "longitude": 1,
                "postalCode": "M5V 1A1",
                "province": "ALBERTA",
                "shortTitle": "123 Main St, Toronto",
                "street": "123 Main St",
                "title": "123 Main St, Toronto",
                "unitNumber": "Suite 100"
              }
            },
            "status": {
              "state": "CANCELLED"
            }
          }
        ],
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "cursor_abc123"
        }
      }
    }
  }
  ```
</ResponseExample>

## Query field

`engagements`

### Arguments

<ParamField path="after" type="String">
  Returns the elements in the list that come after the specified cursor.
</ParamField>

<ParamField path="before" type="String">
  Returns the elements in the list that come before the specified cursor.
</ParamField>

<ParamField path="filters" type="EngagementSearchFilterInput">
  Filters to apply to the engagement search.

  <Expandable title="properties">
    <ParamField path="closingDate" type="DateRangeInput">
      Filter based on engagement closing date.

      <Expandable title="properties">
        <ParamField path="endDate" type="ISO8601Date">
          The end date of the date range.
        </ParamField>

        <ParamField path="startDate" type="ISO8601Date">
          The start date of the date range.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="createdAt" type="DateRangeInput">
      Filter based on engagement creation date.

      <Expandable title="properties">
        <ParamField path="endDate" type="ISO8601Date">
          The end date of the date range.
        </ParamField>

        <ParamField path="startDate" type="ISO8601Date">
          The start date of the date range.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="provinces" type="[Province!]">
      Filter based on province.
    </ParamField>

    <ParamField path="statuses" type="[EngagementStatus!]">
      Filter based on engagement status.
    </ParamField>

    <ParamField path="types" type="[EngagementType!]">
      Filter based on engagement type.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="first" type="Int">
  Returns the first *n* elements from the list.
</ParamField>

<ParamField path="last" type="Int">
  Returns the last *n* elements from the list.
</ParamField>

<ParamField path="query" type="String">
  Text query to search engagements.
</ParamField>

<ParamField path="sortOrder" type="EngagementSearchSortOrder">
  Sort order for results.
</ParamField>

### Return fields

<ResponseField name="engagements" type="EngagementConnection">
  Search and list engagements.

  <Expandable title="properties">
    <ResponseField name="edges" type="[EngagementEdge]">
      A list of edges.

      <Expandable title="properties">
        <ResponseField name="cursor" type="String!" required>
          A cursor for use in pagination.
        </ResponseField>

        <ResponseField name="node" type="Engagement">
          The item at the end of the edge.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nodes" type="[Engagement]">
      A list of nodes.

      <Expandable title="properties">
        <ResponseField name="cancellable" type="Boolean!" required>
          Whether the engagement can be cancelled.
        </ResponseField>

        <ResponseField name="clients" type="[EngagementClient!]!" required>
          The clients on this engagement.
        </ResponseField>

        <ResponseField name="createdAt" type="ISO8601DateTime!" required>
          The time the engagement was created.
        </ResponseField>

        <ResponseField name="id" type="EngagementGID!" required>
          The unique identifier of the engagement.
        </ResponseField>

        <ResponseField name="owner" type="String">
          The name of the engagement owner.
        </ResponseField>

        <ResponseField name="shortId" type="String!" required>
          A short human-readable identifier for the engagement.
        </ResponseField>

        <ResponseField name="type" type="EngagementType!" required>
          The type of the engagement.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pageInfo" type="PageInfo!" required>
      Information to aid in pagination.

      <Expandable title="properties">
        <ResponseField name="endCursor" type="String">
          When paginating forwards, the cursor to continue.
        </ResponseField>

        <ResponseField name="hasNextPage" type="Boolean!" required>
          When paginating forwards, are there more items?
        </ResponseField>

        <ResponseField name="hasPreviousPage" type="Boolean!" required>
          When paginating backwards, are there more items?
        </ResponseField>

        <ResponseField name="startCursor" type="String">
          When paginating backwards, the cursor to continue.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Types

* [`DateRangeInput`](/lender-api/reference/members/inputs/date-range-input) (input) — Input for a date range.
* [`Engagement`](/lender-api/reference/members/interfaces/engagement) (interface) — Represents an engagement.
* [`EngagementClient`](/lender-api/reference/members/objects/engagement-client) (object) — A client contact on an engagement.
* [`EngagementConnection`](/lender-api/reference/members/objects/engagement-connection) (object) — The connection type for Engagement.
* [`EngagementEdge`](/lender-api/reference/members/objects/engagement-edge) (object) — An edge in a connection.
* [`EngagementGID`](/lender-api/reference/members/scalars/engagement-gid) (scalar) — A global identifier for a Engagement object in format of 'gid://ownright/Engagement/ID'.
* [`EngagementSearchFilterInput`](/lender-api/reference/members/inputs/engagement-search-filter-input) (input) — Input to filter results when performing an engagements search.
* [`EngagementSearchSortOrder`](/lender-api/reference/members/enums/engagement-search-sort-order) (enum) — Possible ways to sort results when searching engagements.
* [`EngagementStatus`](/lender-api/reference/members/enums/engagement-status) (enum) — Possible statuses for engagements.
* [`EngagementType`](/lender-api/reference/members/enums/engagement-type) (enum) — The type of engagement.
* [`ISO8601Date`](/lender-api/reference/members/scalars/iso8601-date) (scalar) — An ISO 8601-encoded date
* [`ISO8601DateTime`](/lender-api/reference/members/scalars/iso8601-date-time) (scalar) — An ISO 8601-encoded datetime
* [`PageInfo`](/lender-api/reference/members/objects/page-info) (object) — Information about pagination in a connection.
* [`Province`](/lender-api/reference/members/enums/province) (enum) — Possible provinces.