Skip to main content

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.

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:
Request
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:
Variables
{
  "id": "gid://ownright/Engagement/42"
}
Sample response:
Response
{
  "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": "[email protected]",
          "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. 
{
  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
      }
    }
  }
}
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.

​
Handling a null response

If the engagement ID doesn’t exist or you don’t have access to it, the query returns null: 
{
  "data": {
    "engagement": null
  }
}
Make sure your integration handles this case gracefully.

​
Next steps

Cancelling an engagement

Learn how to cancel an engagement that is no longer needed.

File uploads

Learn the staged upload flow for attaching mortgage documents.