​

What is a Deal?

A Deal represents a complete mortgage transaction package. Think of it as a folder that holds everything related to a mortgage application: the people applying for the loan, the loan(s) themselves, and all the parties involved in the transaction.

​

Why does the Deal entity exist?

Mortgage transactions often involve multiple borrowers, multiple loans, and multiple parties that must be managed together. A single loan entity cannot adequately represent these complex relationships. A single mortgage transaction often involves:

1. Multiple borrowers who share financial responsibility
2. Multiple loans that need to be evaluated together
3. Multiple parties (title companies, appraisers, real estate agents) who work across the entire transaction

​

Deal structures and implications

​

Single loan deals

The most common Deal structure contains a single loan with one or more borrowers. Implications: In single loan Deals, the borrower’s financial profile is evaluated against that one loan. The Deal structure still provides benefits by centralizing borrower information, party management, and providing consistent identification. This structure is straightforward and represents the majority of mortgage transactions. Example: Two borrowers are married and buying their first home. They apply together for a conventional 30-year mortgage. The Deal contains both borrowers (with their combined financial profile) and a single loan for the home purchase. Even with a single loan, the Deal structure provides value by organizing all related entities (borrowers, property, parties) in one place. See the Deal query for how to retrieve this structure.

​

Multiple loan deals (portfolio financing)

Some transactions involve multiple properties or multiple loans that must be underwritten together within a single Deal. Implications: When a Deal contains multiple loans, all loans must be underwritten together. The borrower’s credit, total debt-to-income ratio, and available assets are evaluated holistically across all loans. This ensures proper risk assessment and prevents double-counting of assets or incomplete evaluation of debt load. Example: A real estate investor is purchasing three rental properties simultaneously. The Deal contains three loans, each with its own subject property. The lender evaluates:

• The investor’s total debt load across all three loans
• The combined rental income from all properties
• The investor’s ability to handle vacancies across the portfolio

In this structure, the borrower’s financial profile (credit score, existing liabilities, available assets) is evaluated against the combined obligations of all loans. Each loan’s subject property includes its own rental income projection. The Deal structure ensures proper allocation of assets across down payments and comprehensive risk assessment. Why holistic underwriting matters: See the Borrower and Loan documentation for the complete field reference.

​

Purchase vs. refinance transactions

Deals can represent purchase transactions (buying a new property) or refinance transactions (replacing an existing mortgage). Implications: Purchase and refinance transactions have different requirements and data needs. Purchase transactions require property purchase information, while refinance transactions require information about the existing property and mortgage. The Deal structure accommodates both transaction types while maintaining consistent organization of borrowers and parties. Example (Purchase): The borrower is purchasing a $400,000 home. The Deal contains the borrower, a loan with purchase-specific information (purchase price, down payment), and a subject property representing the home being purchased. Example (Refinance): The borrower has owned their home for 10 years and wants to refinance to a lower rate while taking out $50,000 for home improvements. The Deal contains the borrower, a loan with refinance-specific information (refinance cash-out proceeds), and references to the borrower’s owned property showing current market value and existing loan balance. The key difference is in the loan’s loanPurpose field and related fields like purchasePrice for purchases or refinanceCashOutProceeds for refinances. See the Loan and OwnedProperty documentation for details.

​

DSCR loan transactions

Deals can contain loans that qualify based on property income rather than borrower personal income. Implications: DSCR (Debt Service Coverage Ratio) loans evaluate the property’s rental income against the mortgage payment rather than relying primarily on the borrower’s personal income. The Deal structure allows the borrower’s financial profile to be maintained while the loan qualification focuses on property-specific factors. Example: The borrower is purchasing a rental property. The loan qualification depends on whether the expected rent covers the mortgage payment. The Deal contains the borrower (whose personal income may be less relevant), a loan with DSCR-specific indicators, and a subject property with rental income projections. For DSCR loans, the key data point is the subject property’s rentalEstimatedGrossMonthlyRentAmount, which is compared against the proposed mortgage payment. The borrower’s personal income may be less relevant in this loan type, but their financial profile is still maintained in the Deal structure. See the Loan and SubjectProperty documentation for relevant fields.

​

Key concepts to remember

​

Related entities

For more information on related entities, see the GraphQL API Reference:

• Borrower - Borrower profiles, including income, assets, and credit information.
• Loan - Loan applications, terms, and the underwriting process.
• Party - Third-party service providers managed within a Deal.