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

# Fetching engagement details

> How to retrieve detailed information about a specific engagement

To retrieve information about a specific engagement, use the `engagement` query with
the engagement's GID. Since the `Engagement` type is an interface implemented by
`PurchaseEngagement` and `RefinanceEngagement`, you'll use inline fragments to access
type-specific fields.

## Fetching a single engagement

Use the `engagement(id: EngagementGID!)` query to retrieve details about one engagement:

```graphql Request theme={null}
query GetEngagementDetails($id: EngagementGID!) {
  engagement(id: $id) {
    ... on PurchaseEngagement {
      id
      shortId
      type
      closingDate
      owner
      createdAt
      clients {
        firstName
        lastName
        email
        phoneNumber
      }
      property {
        address {
          street
          unitNumber
          city
          province
          postalCode
          country
        }
      }
      status {
        state
      }
    }
    ... on RefinanceEngagement {
      id
      shortId
      type
      closingDate
      owner
      createdAt
      clients {
        firstName
        lastName
        email
        phoneNumber
      }
      property {
        address {
          street
          unitNumber
          city
          province
          postalCode
          country
        }
      }
      status {
        state
      }
    }
  }
}
```

**Variables:**

```json Variables theme={null}
{
  "id": "gid://ownright/Engagement/42"
}
```

**Sample response:**

```json Response [expandable] theme={null}
{
  "data": {
    "engagement": {
      "id": "gid://ownright/Engagement/42",
      "shortId": "ENG-42",
      "type": "PURCHASE",
      "closingDate": "2025-09-15",
      "owner": "Jane Smith",
      "createdAt": "2025-08-01T14:30:00Z",
      "clients": [
        {
          "firstName": "Jane",
          "lastName": "Doe",
          "email": "jane.doe@example.com",
          "phoneNumber": "+14165551234"
        }
      ],
      "property": {
        "address": {
          "street": "123 Main Street",
          "unitNumber": "Unit 4B",
          "city": "Toronto",
          "province": "ONTARIO",
          "postalCode": "M5V 2T6",
          "country": "CANADA"
        }
      },
      "status": {
        "state": "PREPARING_FOR_CLOSING"
      }
    }
  }
}
```

## Understanding inline fragments

Since the `engagement` query returns the `Engagement` interface, you need inline fragments
to access the concrete type's fields. The interface provides a common set of fields
(`id`, `shortId`, `type`, `owner`, `clients`, `createdAt`), but type-specific fields
like `closingDate`, `property`, and `status` are only available on the concrete types.

```graphql theme={null}
{
  engagement(id: "gid://ownright/Engagement/42") {
    # Fields from the Engagement interface (available on all types)
    id
    shortId
    type
    owner

    # Type-specific fields require inline fragments
    ... on PurchaseEngagement {
      closingDate
      property {
        address {
          street
          city
        }
      }
      status {
        state
      }
    }
    ... on RefinanceEngagement {
      closingDate
      property {
        address {
          street
          city
        }
      }
      status {
        state
      }
    }
  }
}
```

<Info>
  The `status` field is itself an interface with multiple concrete status types
  (one per state). Each status type currently exposes a `state` field, but this
  pattern allows for additional status-specific fields to be added in the future
  without breaking changes.
</Info>

## Handling a null response

If the engagement ID doesn't exist or you don't have access to it, the query returns
`null`:

```json theme={null}
{
  "data": {
    "engagement": null
  }
}
```

Make sure your integration handles this case gracefully.

## Next steps

<CardGroup cols={2}>
  <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>

  <Card title="File uploads" icon="upload" href="/lender-api/guides/file-uploads">
    Learn the staged upload flow for attaching mortgage documents.
  </Card>
</CardGroup>