​

What is a Loan?

A Loan represents an individual mortgage loan application within a Deal. While a Deal can contain multiple loans, each Loan represents a specific mortgage transaction for a particular property with defined terms, purpose, and status. A Loan contains all the information needed to process, underwrite, and close a mortgage transaction, including:

• Loan terms (amount, interest rate, term length)
• Loan purpose (purchase, refinance, cash-out refinance)
• Property information (subject property being financed)
• Financial details (purchase price, down payment, closing costs)
• Loan status and stages (pre-approval, processing, underwriting, clear to close)
• Rate lock information
• Fees and concessions

​

Why does the Loan entity exist?

A Deal can contain multiple loans, but each loan has its own terms, property, and lifecycle. The Loan entity provides the structure needed to manage individual mortgage transactions:

1. Property-Specific Terms - Each loan is tied to a specific subject property with its own purchase price, loan amount, and property characteristics.
2. Loan Purpose Differentiation - Loans can have different purposes (purchase vs. refinance vs. cash-out), each with different requirements and processes.
3. Independent Lifecycle - Each loan progresses through its own stages (pre-approval, processing, underwriting, closing) independently, even when multiple loans exist in the same Deal.
4. Term-Specific Information - Loan amount, interest rate, term length, and other terms are specific to each loan.
5. Rate Lock Management - Each loan can have its own rate lock with different expiration dates and terms.

​

Loan scenarios and lifecycle

​

Creating a loan for a purchase transaction

When a borrower is purchasing a property, you create a loan with purchase-specific information. Example: The borrower is purchasing a $400,000 home with a 20% down payment. You create a loan with loanPurpose set to PURCHASE, purchasePrice set to $400,000, and loanAmount set to $320,000. The loan is associated with a subject property containing the property details. As the loan progresses, you track its stages from pre-approval through closing. In this scenario, the loan is created within a Deal that contains the borrower(s). The loan amount, purchase price, and down payment are tracked, and the loan progresses through its lifecycle independently. See the Loan and SubjectProperty documentation for details.

​

Creating a loan for a refinance transaction

When a borrower is refinancing their existing mortgage, you create a loan with refinance-specific information. Example: The borrower has owned their home for 10 years and wants to refinance to a lower rate. You create a loan with loanPurpose set to REFINANCE. If they’re not taking cash out, refinanceCashOutProceeds is set to 0. If they’re taking cash out, you set refinanceCashOutProceeds to the cash-out amount (e.g., $50,000). The loan is used to pay off the existing mortgage and establish new terms. For refinances, the loan amount is based on the existing mortgage balance, any cash-out amount, and the property’s current value. The refinanceCashOutProceeds field is used in qualification calculations. See the Loan and OwnedProperty documentation for details.

​

Managing multiple loans in a Deal

When a Deal contains multiple loans, each loan is managed independently but shares the borrowers’ financial profile. Example: A real estate investor is purchasing three rental properties simultaneously. You create three separate loans within the same Deal, each associated with its own subject property and having independent loan amounts, terms, and status. All three loans use the same borrowers’ income, assets, and credit information for qualification, but each loan is evaluated independently for property-specific factors. In this scenario, each loan has its own lifecycle and can progress through stages independently. However, the borrowers’ financial profile is evaluated holistically across all loans to ensure they can handle the combined debt load. See the Deal and Loan documentation for how multiple loans are managed.

​

Tracking loan progress through stages

As a loan moves through the mortgage process, you track its current stage and stage history. Example: A loan starts in “Pre-Approval” where initial qualification is determined. As documentation is collected, it moves to “Processing”. When underwriting begins, it moves to “Underwriting”. After approval with conditions, it moves to “Conditionally Approved”. Once all conditions are met, it moves to “Clear to Close”. You query the loan’s currentStage to see where it is, and the stages field shows the complete history. The loan’s currentStage field indicates the current stage, and the stages field contains a chronological history. This allows you to track progress, identify bottlenecks, and understand where each loan is in the process. See the Loan documentation for stage-related fields.

​

Managing rate locks

When a borrower wants to lock in an interest rate, you set the rate lock term and track the lock status. Example: The borrower wants to lock in a 6.5% interest rate for 60 days. You set the loan’s rateLockTerm to 60, and a rate lock is established with an expiration date. You monitor the rate lock status to ensure the loan closes before expiration, as expired locks may require extension fees or result in a new rate. The loan’s rateLockTerm field specifies the number of days the rate is locked. Rate lock status, expiration dates, and terms are tracked separately, allowing you to manage rate locks and ensure timely closing. See the Loan documentation for rate lock fields.

​

Updating loan terms and information

As loan details change during the process, you update the loan entity with new information. Example: During processing, the purchase price changes from $400,000 to $410,000. You update the loan’s purchasePrice field. The borrower decides to increase their down payment, so you update the loanAmount accordingly. Closing costs are finalized, so you update fee information. Each update maintains the loan’s history while reflecting current terms. Loan fields can be updated as information becomes available or changes. This allows you to maintain accurate loan information throughout the process while preserving the ability to track changes. See the Loan documentation for updateable fields.

​

Key concepts to remember

​

Related entities

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

• Deal - The Deal that contains the loan and associated borrowers.
• SubjectProperty - The property being purchased or refinanced with this loan.
• Borrower - The borrowers whose financial profile is used for loan qualification.
• LoanApplication - The loan application associated with the loan.