> ## 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.

# Liabilities

> Understanding the Liability entity - debts and obligations that impact mortgage qualification

# What is a Liability?

A **Liability** represents a debt or financial obligation that a borrower must pay. In mortgage underwriting, liabilities are critical because they directly impact a borrower's **[debt-to-income (DTI) ratio](/entity-models/key-concepts/dti)**, which is one of the primary factors lenders use to determine loan qualification.

Liabilities can include:

* Existing mortgages on other properties
* Credit card debt
* Auto loans
* Student loans
* Personal loans
* Home equity lines of credit (HELOCs)
* Tax liens and judgments
* And other financial obligations

## Why does the Liability entity exist?

Mortgage underwriting requires more than simply using monthly payment amounts in [DTI](/entity-models/key-concepts/dti) calculations. Different types of liabilities are handled differently based on regulatory requirements, lender guidelines, and the specific characteristics of each debt:

1. **Payment vs. Balance** - Some liabilities use the actual monthly payment, while others (like deferred student loans or revolving credit) require special calculations based on the balance.
2. **Property Association** - Liabilities can be tied to specific properties (like a mortgage on an owned property), which affects how rental income and expenses are calculated.
3. **Intent Management** - Borrowers may plan to pay off certain liabilities before or at closing, which changes their impact on qualification.
4. **Exclusion Reasons** - Some liabilities shouldn't count toward DTI (e.g., business debts paid from business funds, debts assigned to another party).

## Types of liabilities and implications

### Standard installment and revolving debt

Standard liabilities include auto loans, personal loans, credit cards, and other debts with regular monthly payments.

**Implications:** These liabilities use their actual `monthlyPayment` amount in [DTI](/entity-models/key-concepts/dti) calculations. The payment amount is straightforward and directly impacts the borrower's debt-to-income ratio.

**Example:** The borrower has a car loan with a \$350 monthly payment and credit cards with a \$200 minimum payment. Both liabilities are included in their [DTI](/entity-models/key-concepts/dti) calculation using these payment amounts.

For standard installment debt (auto loans, personal loans), the `monthlyPayment` field is used directly. For revolving credit accounts (credit cards, lines of credit), lenders typically use 5% of the outstanding balance as the monthly payment, even if the minimum payment is lower, to ensure conservative underwriting.

<Warning>
  **Revolving credit calculation:** Lenders use 5% of the outstanding balance
  for revolving credit accounts in [DTI](/entity-models/key-concepts/dti) calculations, regardless of the actual
  minimum payment. This ensures conservative underwriting by assuming higher
  utilization.
</Warning>

See the [Liability](https://pylon.mortgage/documentation/graphql/index.html) documentation for how different liability types are handled.

### Deferred student loans

Student loans in deferment require special handling because the actual payment may be \$0, but lenders must still account for the debt in [DTI](/entity-models/key-concepts/dti) calculations.

**Implications:** Instead of using the actual payment amount, lenders calculate an effective monthly payment based on a percentage of the loan balance. This ensures the debt is properly accounted for even when payments aren't currently being made.

**Example:** The borrower has \$50,000 in deferred student loans. Even though they're not making payments currently, the lender must calculate an effective monthly payment for [DTI](/entity-models/key-concepts/dti) purposes. Under Fannie Mae guidelines, this would typically be 1% of the balance (\$500/month), but the calculation method varies by agency.

<Info>
  **How deferred student loans are calculated:** Fannie Mae and Freddie Mac
  treat deferred student loans differently. Fannie Mae typically requires using
  1% of the outstanding balance as the monthly payment amount for [DTI](/entity-models/key-concepts/dti)
  calculations, whereas Freddie uses 0.5% of the outstanding balance. The
  specific calculation method depends on the loan program and agency guidelines
  being followed.
</Info>

For deferred student loans, the system uses the `balance` field to calculate the effective monthly payment, not the `monthlyPayment` field. See the [Liability](https://pylon.mortgage/documentation/graphql/index.html) documentation for the `type` field to identify `DEFERRED_STUDENT_LOAN` liabilities.

### Property-associated liabilities

Mortgages and liens on properties owned by the borrower are liabilities that may be associated with those properties.

**Implications:** When a liability is associated with a property that generates rental income, the net effect (rental income minus mortgage payment) is what matters for qualification, not the liability payment alone. This can result in either a positive or negative impact on qualification.

**Example 1 (Positive Net Effect):** The borrower owns a rental property with a \$1,200/month mortgage payment. The property generates \$1,800/month in rental income. The net effect is +\$600/month, which actually improves their qualification rather than hurting it.

**Example 2 (Negative Net Effect):** The borrower owns a rental property with a \$2,500/month mortgage payment. The property generates \$1,800/month in rental income, but the mortgage payment exceeds the rental income. The net effect is -\$700/month, which counts as a liability in their [DTI](/entity-models/key-concepts/dti) calculation. This negative cash flow reduces their qualifying income.

Property-associated liabilities are linked to an `OwnedProperty` via the `ownedPropertyId` field. The system evaluates the property's rental income against its associated liabilities to calculate the net monthly impact. See the [OwnedProperty](https://pylon.mortgage/documentation/graphql/index.html) and [Liability](https://pylon.mortgage/documentation/graphql/index.html) documentation for details.

### Liabilities with payment intent

Borrowers may plan to pay off certain liabilities before or at closing, or subordinate them to the new mortgage.

**Implications:** The `intent` field determines whether a liability counts toward [DTI](/entity-models/key-concepts/dti) calculations. Liabilities that will be paid off are excluded from [DTI](/entity-models/key-concepts/dti), while those that will remain (including subordinated ones) continue to count.

The `intent` field on a liability determines whether it counts toward [DTI](/entity-models/key-concepts/dti) calculations:

| Intent Value         | Description                                                                                            | DTI Impact        |
| -------------------- | ------------------------------------------------------------------------------------------------------ | ----------------- |
| `DO_NOTHING`         | Liability remains active and continues as normal                                                       | Counts toward DTI |
| `PAY_AT_CLOSING`     | Liability will be paid at closing using loan proceeds or assets                                        | Excluded from DTI |
| `PAY_BEFORE_CLOSING` | Liability will be paid before closing using borrower's funds                                           | Excluded from DTI |
| `SUBORDINATE`        | Liability will remain but be subordinated to the new mortgage (common for HELOCs and second mortgages) | Counts toward DTI |

**Example:** The borrower has a \$5,000 credit card balance that they plan to pay off at closing using cash from their savings account. The liability's `intent` is set to `PAY_AT_CLOSING`, so it's excluded from [DTI](/entity-models/key-concepts/dti) calculations.

See the [Liability](https://pylon.mortgage/documentation/graphql/index.html) documentation for the `intent` field and related mutations.

### Excluded liabilities

Some liabilities shouldn't count toward [DTI](/entity-models/key-concepts/dti) for various reasons, such as business debts paid from business funds, debts assigned to another party, or utilities.

**Implications:** When a liability has an `exclusionReason`, it's excluded from [DTI](/entity-models/key-concepts/dti) calculations entirely. This provides transparency in underwriting decisions and ensures only relevant debts impact qualification.

**Example:** The borrower has a business credit card that's paid from their business account, not personal funds. The liability's `exclusionReason` is set to `BUSINESS_DEBT_PAID_FROM_BUSINESS_FUNDS`, so it doesn't count toward their personal [DTI](/entity-models/key-concepts/dti).

Common exclusion reasons include business debts paid from business funds, debts assigned to another party, debts paid by others, utilities, and debts with less than 10 months remaining. When a liability has an `exclusionReason`, it's excluded from [DTI](/entity-models/key-concepts/dti) calculations. See the [Liability](https://pylon.mortgage/documentation/graphql/index.html) documentation for all available exclusion reasons.

## Managing self-reported liabilities

Every liability has a `reportType` that identifies where it came from:

* `CREDIT_REPORT` — pulled from a credit bureau report
* `SELF_REPORTED` — added manually (for example, a debt that hasn't yet appeared on the credit report, or one disclosed by the borrower)

Only **self-reported** liabilities can be created and deleted through the API. Credit-report liabilities are effectively read-only — corrections must flow through the credit report itself and a new report pull.

### Create a self-reported liability

Liabilities created via `liability.create` are assigned `reportType: SELF_REPORTED` by default.

```graphql theme={null}
mutation CreateLiability {
  liability {
    create(
      input: {
        borrowerIds: ["borrower-id"]
        type: CREDIT_CARD
        creditorName: "Example Bank"
        balance: 5000
        monthlyPayment: 150
        intent: DO_NOTHING
      }
    ) {
      liability {
        id
        reportType
      }
    }
  }
}
```

### Delete a self-reported liability

`liability.delete` performs a soft delete: the underlying record is preserved for audit purposes, but the liability no longer counts toward [DTI](/entity-models/key-concepts/dti) or appears in queries. The mutation requires the `delete:liability` OAuth scope.

```graphql theme={null}
mutation DeleteLiability {
  liability {
    delete(input: { id: "liability-id" }) {
      id
      userErrors {
        code
        message
      }
    }
  }
}
```

<Warning>
  Deleting a liability sourced from a credit report is not permitted. If the
  target liability has `reportType: CREDIT_REPORT`, the mutation returns a
  `userErrors` entry with the message `Cannot delete liabilities from credit
      report` and no record is deleted. To remove such an entry, correct it at the
  credit-report source and re-pull the report.
</Warning>

## Key concepts to remember

<AccordionGroup>
  <Accordion title="Liabilities can be associated with borrowers, owned properties, or subject properties">
    A liability can be linked to a borrower directly, or it can be associated
    with a property (either an owned property or the subject property of the
    loan). Property-associated liabilities are typically mortgages or liens on
    that specific property.
  </Accordion>

  <Accordion title="Payment calculation varies by liability type">
    Not all liabilities use their actual monthly payment in DTI calculations.
    Deferred student loans use 1% of balance, revolving credit uses 5% of
    balance, and some liabilities may be excluded entirely based on intent or
    exclusion reason.
  </Accordion>

  <Accordion title="Intent determines inclusion in DTI">
    The `intent` field is critical for [DTI](/entity-models/key-concepts/dti) calculations. Liabilities marked as
    `PAY_AT_CLOSING` or `PAY_BEFORE_CLOSING` are excluded from [DTI](/entity-models/key-concepts/dti), while
    `DO_NOTHING` liabilities are included. `SUBORDINATE` is used for HELOCs and
    second mortgages that will remain but be subordinated to the new loan.
  </Accordion>

  <Accordion title="Exclusion reasons provide underwriting clarity">
    When a liability shouldn't count toward [DTI](/entity-models/key-concepts/dti), the `exclusionReason` field
    documents why. This provides transparency in underwriting decisions and
    helps explain why certain debts don't impact qualification.
  </Accordion>

  <Accordion title="Property liabilities interact with rental income">
    When a liability is associated with an owned property that generates rental
    income, the net effect (income minus liability payment) is what matters for
    qualification, not the liability payment alone.
  </Accordion>
</AccordionGroup>

## Related entities

For more information on related entities, see the [GraphQL API Reference](https://pylon.mortgage/documentation/graphql/index.html):

* **Borrower** - Borrower profiles that own liabilities and are evaluated for [DTI](/entity-models/key-concepts/dti).
* **OwnedProperty** - Properties owned by borrowers that may have associated mortgage liabilities.
* **SubjectProperty** - The property being purchased or refinanced, which may have existing liens.
* **LoanApplication** - The loan application that contains the borrower's liabilities.