> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylon.mortgage/llms.txt
> Use this file to discover all available pages before exploring further.
# Loan
> Understanding the Loan entity - individual mortgage loan applications within a Deal
# 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](/entity-models/key-concepts/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](/entity-models/key-concepts/rate-lock) Management** - Each loan can have its own [rate lock](/entity-models/key-concepts/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` and `purchasePrice` set to \$400,000; the loan's `maxLoanAmount` reflects the maximum financeable amount (here \$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](https://pylon.mortgage/documentation/graphql/index.html) and [SubjectProperty](https://pylon.mortgage/documentation/graphql/index.html) 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.
**Refinance types:** A "rate and term" refinance has
`refinanceCashOutProceeds` set to `0` or `null`-the loan only pays off the
existing mortgage. A "cash-out" refinance has a positive
`refinanceCashOutProceeds` value, allowing the borrower to access home equity.
Cash-out refinances typically have stricter requirements and may affect
pricing.
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](https://pylon.mortgage/documentation/graphql/index.html) and [OwnedProperty](https://pylon.mortgage/documentation/graphql/index.html) 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](https://pylon.mortgage/documentation/graphql/index.html) and [Loan](https://pylon.mortgage/documentation/graphql/index.html) 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.
**Common loan stages:** Pre-Approval (initial qualification), Processing
(documentation collection), Underwriting (detailed evaluation), Conditionally
Approved (pending conditions), Clear to Close (ready for closing), Funding
(loan funded), Closed (loan closed and recorded).
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](https://pylon.mortgage/documentation/graphql/index.html) documentation for stage-related fields.
### Detecting when a loan has actually funded
Once a loan is disbursed, the funding date is exposed on the loan itself via the **`fundedDate`** field.
**Example:** After a loan reaches the "Funding" stage and the wire is sent, `fundedDate` is populated with the calendar date on which the loan was actually funded. Before funding, the field is `null`. To detect that a loan has funded, query `fundedDate` and treat any non-null value as the source of truth for "this loan is funded":
```graphql theme={null}
query LoanFundedAt($loanId: ID!) {
loan(id: $loanId) {
id
currentStage
closingDate
fundedDate
}
}
```
`fundedDate` is distinct from `closingDate`. `closingDate` is the close date on the loan file itself — the date all documents are prepared and executed against, and the anchor for [TRID](/entity-models/key-concepts/trid) timing checks. `fundedDate` is the calendar date the wire actually went out. Whether the two match depends on the loan purpose:
* **Refinances** — `fundedDate` is always *after* `closingDate`. Federal law gives the borrower a three-business-day right of rescission on most owner-occupied refinances, and the wire cannot leave until that window closes.
* **Purchases** — `fundedDate` and `closingDate` are almost always the same day. The main exception is when funding authorization comes in late enough that the wire has to go out the following business day.
Use `closingDate` to schedule and to drive disclosure timing; use `fundedDate` to confirm the loan actually funded.
**`fundedDate` is calendar-day granularity.** It is exposed as a `Date`
scalar (`YYYY-MM-DD`) — not a full timestamp — so use it to answer
"*which day* did this loan fund?", not "what time was the wire sent?".
A `null` value means "not yet funded"; no separate "is funded" flag is
needed.
### Managing rate locks
When a borrower wants to lock in an interest rate, you set the [rate lock](/entity-models/key-concepts/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](/entity-models/key-concepts/rate-lock) is established with an expiration date. You monitor the [rate lock](/entity-models/key-concepts/rate-lock) status to ensure the loan closes before expiration, as expired locks may require extension fees or result in a new rate.
**[Rate lock](/entity-models/key-concepts/rate-lock) expiration:** [Rate locks](/entity-models/key-concepts/rate-lock) have expiration dates. If a loan doesn't
close before expiration, the borrower may face additional costs to extend the
lock or may need to accept current market rates. Track [rate lock](/entity-models/key-concepts/rate-lock) status and
expiration dates to avoid unexpected costs.
The loan's `rateLockTerm` field specifies the number of days the rate is locked. [Rate lock](/entity-models/key-concepts/rate-lock) status, expiration dates, and terms are tracked separately, allowing you to manage [rate locks](/entity-models/key-concepts/rate-lock) and ensure timely closing. See the [Loan](https://pylon.mortgage/documentation/graphql/index.html) documentation for [rate lock](/entity-models/key-concepts/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 the loan's `maxLoanAmount` is adjusted 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](https://pylon.mortgage/documentation/graphql/index.html) documentation for updateable fields.
## Key concepts to remember
Loans are associated with a Deal, and the Deal contains the borrowers whose
financial profile is used for qualification. Multiple loans in a Deal share
the same borrowers but have independent terms, properties, and lifecycles.
Every loan is associated with a specific subject property (the property
being purchased or refinanced). The property's characteristics (value,
location, type) affect loan terms and qualification.
Different loan purposes (purchase, refinance, cash-out) have different
requirements, documentation needs, and may affect available loan products
and pricing.
Loans move through various stages from application to closing. Each stage
represents a different phase of the loan process, and the current stage
indicates where the loan is in its lifecycle.
Rate locks allow borrowers to secure an interest rate for a specified
period, protecting them from rate increases during the loan process. Rate
locks have expiration dates and may require extension fees if the loan
doesn't close in time.
When a Deal contains multiple loans, each loan is evaluated independently
for property-specific factors, but the borrowers' financial profile is
evaluated holistically across all loans to ensure they can handle the
combined debt load.
## Related entities
For more information on related entities, see the [GraphQL API Reference](https://pylon.mortgage/documentation/graphql/index.html):
* **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.