Core Concepts
Referrals and matters
The two foundational objects that play a critical role in the Partner API
Understanding how referrals and matters work is essential to integrating with the
Ownright Developer Platform. These are the two foundational objects that represent
the lifecycle of a real estate legal transaction — from initial client handoff to final
legal completion.
🧩 The real-world analogy
Think of a referral as a warm introduction — you or your product has identified someone who needs real estate legal support, and you’re handing them off to Ownright to help with their transaction. Once that referral is accepted and the client agrees to move forward, it becomes a matter — the actual legal file that our team opens, works on, and completes. These two stages mirror the real-world journey of a client:
Why we modeled it this way
Real estate transactions are complex, dynamic, and timeline-sensitive. We’ve structured the referral and matter models to reflect how legal work happens in the real world:- Separation of referral vs matter helps partners track both pipeline and active files
- Status-driven lifecycles allow for clear communication and automation
- Granular types and transitions give you transparency and actionable insights throughout the transaction
🤝 Referrals
A referral is your way of introducing a potential client to Ownright. It contains basic information about the client, the type of matter, and any contextual details. Once a referral is submitted, our client success team attempts to contact the client, confirm matter details, and determine if the matter is serviceable. Right now, Ownright supports accepting four different types of referrals:- Purchase - a purchase where your client is the purchaser.
- Sale - a sale where your client is the seller.
- Refinance - a refinance where your client is the borrower.
- Status Certificate Review - a status certificate review where your client is the prospective purchaser.
Referral lifecycle
A referral has a relatively straightforward lifecycle:
- Open - The referral has been received and is awaiting contact or qualification.
- Converted - The referral was successful — the client has agreed and a matter has been created.
- Retired - The referral is closed without conversion. This can happen if the client chose another provider, the transaction is no longer proceeding, or Ownright could not service it.
Every referral object returned in the API includes a
status field to
indicate where it stands in its lifecycle. Similarly you can subscribe to
webhook events to get notified about changes to a referral’s status. It is
possible for a referral to be reopened after it has been marked converted or
retired. Read the Partner API Reference
to better understand the structure of a referral object.🏡 Matters
A matter represents an active legal file. This is where real legal work happens: title searches, document signing, registration, and more. Each matter is handled by our legal team and tracked within the Ownright platform. It is not surprising that Ownright supports the same kind of matters as it does referrals, this is because referrals feed into matters. To reiterate, the currently supported matters are purchase, sale, refinance, and status certificate reviews.Purchase, sale, and refinance lifecycle
Purchases, sales, and refinances all share the same lifecycle (for now):
- Before closing - The file has been opened and legal prep is underway.
- Closing in progress - We’re actively handling closing day tasks — registration, etc.
- After closing - The matter has closed, but post-closing tasks (e.g., reporting, final communication) are being finalized.
- Completed - The legal work is fully done.
- Abandoned - The matter fell through or was cancelled.
Status certificate review lifecycle
Status certificate reviews are slightly different from the other types of matters:
- In Progress - The review is underway by our team.
- Completed - The review has been completed.
- Abandoned - Review was cancelled, withdrawn, or otherwise stopped.