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

> The foundational object representing a real estate legal file in the Lender API

An **engagement** is the core object in the Lender API. It represents a real estate legal file
that Ownright manages on behalf of your lending organization. When you submit a new file through
the API, you're creating an engagement that our legal team will open, work on, and close.

## Types of engagements

The Lender API supports two types of engagements, each corresponding to a different kind of
real estate transaction:

<ol>
  <li>
    **Purchase** — A transaction where your borrower is purchasing a property.
    Created using the `purchase` field on `EngagementCreateInput`.
  </li>

  <li>
    **Refinance** — A transaction where your borrower is refinancing an existing
    mortgage on their property. Created using the `refinance` field on
    `EngagementCreateInput`.
  </li>
</ol>

Both types share a common set of fields through the `Engagement` interface (such as `id`,
`clients`, `owner`, and `type`), but each has its own status model and type-specific fields
like `property` and `closingDate`.

## Engagement lifecycle

Every engagement follows a predictable lifecycle from the moment it's received to when
the transaction is fully closed (or cancelled). The diagram below illustrates the typical
progression:

<img className="block dark:hidden" src="https://mintcdn.com/ownright/nd6lo_Agh9Jm7utf/images/engagement-lifecycle-light.png?fit=max&auto=format&n=nd6lo_Agh9Jm7utf&q=85&s=9a6f47d305c8fe3b75110c23f1f6a68e" alt="Engagement Lifecycle Light" width="2064" height="1104" data-path="images/engagement-lifecycle-light.png" />

<img className="hidden dark:block" src="https://mintcdn.com/ownright/nd6lo_Agh9Jm7utf/images/engagement-lifecycle-dark.png?fit=max&auto=format&n=nd6lo_Agh9Jm7utf&q=85&s=be73085f5c009048a692a4a6fd92532b" alt="Engagement Lifecycle Dark" width="2064" height="1104" data-path="images/engagement-lifecycle-dark.png" />

### Engagement states

Both purchase and refinance engagements share the same set of states:

<ol>
  <li>
    **Received** — Ownright has received engagement details and is actively
    reviewing the information.
  </li>

  <li>
    **Setting up** — Ownright is actively setting up the engagement to begin
    closing preparation.
  </li>

  <li>
    **In progress** — The engagement is actively being worked on by the Ownright
    legal team.
  </li>

  <li>
    **Preparing for closing** — The engagement is being prepared for closing
    day. Documents are being reviewed, title work is underway, and the legal
    team is coordinating with all parties.
  </li>

  <li>
    **Closing in progress** — Final closing actions are in motion and the deal
    is set to close today.
  </li>

  <li>**Closed** — The engagement has been successfully funded and closed.</li>

  <li>
    **Complete** — All post-closing tasks have been finalized and the engagement
    is fully complete.
  </li>

  <li>
    **Cancelled** — The engagement has been cancelled and is no longer being
    worked on. This can happen at any point in the lifecycle.
  </li>
</ol>

<Info>
  The `status` field on `PurchaseEngagement` and `RefinanceEngagement` is an
  interface (`PurchaseEngagementStatus` / `RefinanceEngagementStatus`) that
  contains a `state` enum. Use inline fragments to access the state — see the
  [Fetching engagement details](/lender-api/guides/fetching-engagement-details)
  guide for examples.
</Info>

## Key related objects

Each engagement is associated with several important objects:

* **EngagementClient** — The borrower(s) on the engagement. Each client has a `firstName`,
  `lastName`, `email`, and optional `middleName` and `phoneNumber`.
* **Property** — The real estate property involved in the transaction. Contains an `Address`
  with the full street address, city, province, and postal code.
* **TeamMember** — The person within your lending organization who owns the engagement.
  The `owner` field on an engagement displays this team member's name. See the
  [Lender and team members](/lender-api/core-concepts/lender-and-team-members) core concept
  for more details.

## Next steps

Now that you understand engagements, you're ready to start working with them:

<CardGroup cols={2}>
  <Card title="Lender and team members" icon="users" href="/lender-api/core-concepts/lender-and-team-members">
    Learn about your organization and team member objects.
  </Card>

  <Card title="Creating an engagement" icon="plus" href="/lender-api/guides/creating-an-engagement">
    Learn how to submit a new file to Ownright through the API.
  </Card>

  <Card title="Searching engagements" icon="magnifying-glass" href="/lender-api/guides/searching-engagements">
    Filter, sort, and paginate through your engagements.
  </Card>

  <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="File uploads" icon="upload" href="/lender-api/guides/file-uploads">
    Understand the staged file upload flow for attaching documents.
  </Card>
</CardGroup>