> ## 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. # 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: Real World Analogy Light Real World Analogy Dark ### 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:
  1. **Separation of referral vs matter** helps partners track both pipeline and active files
  2. **Status-driven lifecycles** allow for clear communication and automation
  3. **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:
  1. Purchase - a purchase where your client is the purchaser.
  2. Sale - a sale where your client is the seller.
  3. Refinance - a refinance where your client is the borrower.
  4. Status Certificate Review - a status certificate review where your client is the prospective purchaser.
### Referral lifecycle A referral has a relatively straightforward lifecycle: Referral Lifecycle Light Referral Lifecycle Dark
  1. **Open** - The referral has been received and is awaiting contact or qualification.
  2. **Converted** - The referral was successful — the client has agreed and a matter has been created.
  3. **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](/partner-api/reference/connecting) 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): Matter Lifecycle Light Matter Lifecycle Dark
  1. **Before closing** - The file has been opened and legal prep is underway.
  2. **Closing in progress** - We’re actively handling closing day tasks — registration, etc.
  3. **After closing** - The matter has closed, but post-closing tasks (e.g., reporting, final communication) are being finalized.
  4. **Completed** - The legal work is fully done.
  5. **Abandoned** - The matter fell through or was cancelled.
### Status certificate review lifecycle Status certificate reviews are slightly different from the other types of matters: Status Certificate Review Lifecycle Light Status Certificate Review Lifecycle Dark
  1. **In Progress** - The review is underway by our team.
  2. **Completed** - The review has been completed.
  3. **Abandoned** - Review was cancelled, withdrawn, or otherwise stopped.
## 🚀 Ready to go! By understanding referrals and matters, you’re equipped to guide your clients through every step of the closing journey, while keeping your systems in sync with the legal work being done by Ownright behind the scenes. ## Next steps Start sending clients to Ownright programmatically by creating a referral. Understand how to authenticate your requests to the Partner API.