Skip to main content
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:
  1. Purchase — A transaction where your borrower is purchasing a property. Created using the purchase field on EngagementCreateInput.
  2. Refinance — A transaction where your borrower is refinancing an existing mortgage on their property. Created using the refinance field on EngagementCreateInput.
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: Engagement Lifecycle Light

​
Engagement states

Both purchase and refinance engagements share the same set of states:
  1. Received — Ownright has received engagement details and is actively reviewing the information.
  2. Setting up — Ownright is actively setting up the engagement to begin closing preparation.
  3. 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.
  4. Closing in progress — Final closing actions are in motion and the deal is set to close today.
  5. Closed — The engagement has been successfully funded and closed.
  6. Cancelled — The engagement has been cancelled and is no longer being worked on. This can happen at any point in the lifecycle.
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 guide for examples.
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 core concept for more details.

​
Next steps

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

Creating an engagement

Learn how to submit a new file to Ownright through the API.

Searching engagements

Filter, sort, and paginate through your engagements.

Fetching engagement details

Retrieve detailed information about a specific engagement.

File uploads

Understand the staged file upload flow for attaching documents.