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

# Incomes

> Understanding the Income entity - sources of revenue used for mortgage qualification

# What is an Income?

An **Income** represents a source of revenue that a borrower receives, which is used to calculate [debt-to-income (DTI)](/entity-models/key-concepts/dti) ratios and determine loan qualification. The Pylon API supports a comprehensive range of income types, from standard employment wages to specialized military allowances, rental income, and more.

Income information includes:

* Income type (employment, self-employment, rental, military, etc.)
* Stated amount and pay frequency
* Qualified amount (after applying guidelines, before verification)
* Verified amount (after documentation review)
* Employment or business details
* Property information for rental income
* Special considerations for military, retirement, and other income types

## Why does the Income entity exist?

Mortgage underwriting requires accurate income calculations that go beyond simply using stated amounts. The Income entity provides the structure needed to properly evaluate borrower income:

1. **Three-Tiered Income States** - Pylon uses stated, qualified, and verified income to provide accurate qualification calculations throughout the loan process, even before documentation is submitted.
2. **Guideline Application** - Qualified income applies mortgage guidelines (Fannie Mae, Freddie Mac, FHA, VA, USDA, etc.) to stated income before documentation is received, giving loan officers and borrowers an accurate view of [DTI](/entity-models/key-concepts/dti) and qualification potential.
3. **Comprehensive Income Types** - The system supports dozens of income types, from standard employment to specialized military allowances, rental income, retirement benefits, and more.
4. **Verification Requirements** - Different income types have different verification requirements, and the system tracks what documentation is needed for each.
5. **Pay Period Handling** - Income can be received at various frequencies (weekly, bi-weekly, monthly, etc.), and the system properly converts these to monthly amounts for qualification calculations.

## Understanding income states: stated, qualified, and verified

Pylon uses three distinct income states to provide accurate qualification calculations throughout the loan process. This three-tiered approach ensures that loan officers and borrowers have a realistic view of qualification potential even before documentation is submitted.

### Stated income

**Stated income** is the raw data provided by the borrower through the loan application, whether submitted via Pylon Elements, the GraphQL API, or other integration methods. This represents the borrower's self-reported income information before any validation or guideline application.

Stated income is the starting point for all income calculations. It includes:

* The amount the borrower reports earning
* The frequency of payment (weekly, bi-weekly, monthly, etc.)
* The type of income (employment, self-employment, rental, etc.)
* Any additional context provided by the borrower

**Important**: Stated income is not validated against mortgage guidelines at this stage. It's simply what the borrower has told you.

### Qualified income

**Qualified income** is a calculated value that applies mortgage guidelines to the stated income **before** documentation is received or verified. This is one of Pylon's key differentiators from traditional Loan Origination Systems (LOS).

The qualified amount is determined by:

1. Taking the stated income
2. Applying all relevant mortgage guidelines (Fannie Mae, Freddie Mac, FHA, VA, USDA, etc.)
3. Calculating what the income would qualify as if documentation were to support it

**Why this matters**: Many LOS systems will use stated income in [DTI](/entity-models/key-concepts/dti) calculations if documentation hasn't been received yet. This creates a poor borrower experience because it shows an inflated [DTI](/entity-models/key-concepts/dti) ratio that doesn't reflect reality. For example, if a self-employed borrower reports 8 months of income, but guidelines require 24 months of continuous self-employment, the qualified income will be \$0-even before documentation is reviewed.

**Example Scenario**:

* Borrower states: \$10,000/month from self-employment for 8 months
* Guidelines require: 24 months of continuous self-employment
* **Qualified income**: \$0/month (because the 8-month history doesn't meet the 24-month requirement)

This gives loan officers and borrowers an accurate view of [DTI](/entity-models/key-concepts/dti) and qualification potential **before** spending time and money on documentation that won't change the outcome.

### Verified income

**Verified income** is the final, documentation-backed amount that has been:

1. Proven through documentation (W-2s, pay stubs, tax returns, bank statements, etc.)
2. Validated against mortgage guidelines
3. Confirmed through automated verification integrations (Day 1 Certainty, Automated Income Model, etc.)

The `verifiedAmount` field on an Income entity indicates whether income has been verified:

* **`verifiedAmount` is `null`**: Income has not been verified yet, or verification is not available. The income amount shown in `statedAmount` or `statedMonthlyAmount` is what the borrower stated, but it hasn't been verified.
* **`verifiedAmount` has a value**: Income has been successfully verified. The value represents the verified monthly income amount. Pylon's underwriting system uses this verified amount without requiring additional documentation.

#### Verification methods

Income can be verified through two methods:

1. **Automated verification (D1C/AIM)** - Income verified through Day 1 Certainty (D1C) or Automated Income Model (AIM) approved services:

   * **Truv** - Account connection-based verification (requires borrower opt-in and your API call to request a token and initialize Truv Bridge)
   * **The Work Number** - SSN-based verification (fully automatic, no borrower action required)
   * When income is verified through these sources, the `verifiedAmount` field is automatically populated, and no additional documentation is typically required
   * See the [Income Verification guide](/guides/getting-started/order-outs-and-integrations/d1c-aim/income-verification) for complete details on how these integrations work, including setup, workflows, and best practices

2. **Manual verification** - Income verified through traditional documentation:
   * For W-2 employment income: Last two years of W-2s and last two pay stubs with year-to-date (YTD) values
   * For self-employment: Tax returns (1040), Schedule C/E/K-1, YTD P\&L, business bank statements
   * The verified amount is calculated based on the actual documented earnings
   * Guidelines are applied to ensure the income meets all requirements

Verified income is the authoritative value that Pylon's underwriting system uses for final underwriting decisions and loan approval.

## Types of incomes and implications

### Employment income

Employment income includes all forms of compensation from work, whether as an employee or self-employed. See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for field details.

| Income Type             | History Required     | Key Verification Documents                                                            | Notes                                                                                                             |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Standard Employment** | 2 years              | Last 2 years W-2s, last 2 pay stubs with YTD                                          | Most common income type. Straightforward to verify.                                                               |
| **Self-Employment**     | 24 months continuous | Last 2 years tax returns (1040), Schedule C/E/K-1, YTD P\&L, business bank statements | <Warning>Qualified income will be \$0 if history requirement not met, even before documentation review.</Warning> |
| **Commissions**         | 2 years              | Tax returns, commission statements                                                    | Income averaged over 24 months to establish stability.                                                            |
| **Bonus**               | 2 years (recurring)  | Employment contracts, pay stubs                                                       | One-time bonuses typically don't count. Recurring bonuses may qualify.                                            |
| **Overtime**            | 2 years              | Pay stubs, W-2s showing patterns                                                      | Inconsistent overtime may result in only base salary qualifying.                                                  |
| **Tips**                | Varies               | Tax returns                                                                           | May require additional verification for cash tips.                                                                |
| **Contract Basis**      | 24 months            | Contracts, invoices, tax returns                                                      | Similar to self-employment requirements.                                                                          |

#### Standard employment income

Regular W-2 employment income from a traditional employer. This is the most common income type.

**Example:** The borrower reports \$5,000/month salary, paid bi-weekly, with 3 years of employment history. The qualified income is \$5,000/month because all guidelines are satisfied. After verification with W-2s and pay stubs, the verified amount confirms the qualified amount.

For standard employment income, the `statedAmount` and `payPeriodFrequency` fields are used to calculate monthly income. The `employment` field contains employer information and start date. See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for employment-related fields.

#### Self-employment income

Income from self-employment, including sole proprietorships, partnerships, and other business structures.

**Example:** The borrower reports \$12,000/month from freelance consulting, but has only been self-employed for 6 months. The qualified income is \$0/month because the 6-month history doesn't meet the 24-month requirement, even before documentation is reviewed.

<Warning>
  **Self-employment requirements:** Conventional loans typically require 24
  months of continuous self-employment history. If the borrower has less than 24
  months, the qualified income will be \$0, regardless of the stated amount or
  documentation quality.
</Warning>

### Military income

Pylon supports various types of military income to accurately represent service member compensation. Military income is generally stable and reliable. Some allowances may not be counted toward qualification (varies by loan program). Combat pay is typically excluded from income calculations.

| Income Type                                   | Typically Counts | Notes                                                |
| --------------------------------------------- | ---------------- | ---------------------------------------------------- |
| **Military Base Pay**                         | Yes              | Standard military salary                             |
| **Military Variable Housing Allowance (VHA)** | Yes              | Housing allowance that varies by location            |
| **Military Quarters Allowance**               | Varies           | Housing allowance for on-base housing                |
| **Military Rations Allowance**                | Varies           | Food allowance - may be excluded by loan program     |
| **Military Clothes Allowance**                | Varies           | Uniform and clothing allowance                       |
| **Military Combat Pay**                       | No               | Additional pay for combat zones - typically excluded |
| **Military Flight Pay**                       | Yes              | Additional pay for flight duties                     |
| **Military Hazard Pay**                       | Yes              | Additional pay for hazardous duties                  |
| **Military Overseas Pay**                     | Yes              | Additional pay for overseas assignments              |
| **Military Prop Pay**                         | Yes              | Pro-pay for medical professionals                    |

**Example:** The borrower is an active-duty service member with base pay of \$4,000/month, VHA of \$2,000/month, and rations allowance of \$400/month. The qualified income includes base pay and VHA, but rations allowance may be excluded depending on the loan program.

See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for all military income types.

### Rental and property income

Income generated from real estate properties owned by the borrower.

| Income Type               | Key Documents                                 | Notes                                                                  |
| ------------------------- | --------------------------------------------- | ---------------------------------------------------------------------- |
| **Net Rental Income**     | Lease agreements, Schedule E, bank statements | Net income (after expenses) counts toward qualification                |
| **Proposed Gross Rent**   | Market analysis, comparable rents             | For investment properties being purchased                              |
| **Accessory Unit Income** | Lease agreements, permits                     | ADU must be legal and properly permitted                               |
| **Boarder Income**        | Lease agreements, tax returns                 | May have restrictions for primary residences depending on loan program |

**Example:** The borrower owns a rental property that generates \$1,800/month in rent. After expenses (mortgage payment, maintenance, taxes, insurance) of \$1,200/month, the net rental income is \$600/month. This \$600/month counts toward qualification.

For rental income, the property address, monthly rental amount, and expenses are tracked. The net income calculation determines the qualified amount. See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) and [OwnedProperty documentation](https://pylon.mortgage/documentation/graphql/index.html) for details.

### Retirement and benefits income

Income from retirement plans, government benefits, and disability programs.

| Income Type                          | Continuation Required | Key Documents                                                |
| ------------------------------------ | --------------------- | ------------------------------------------------------------ |
| **Pension Income**                   | 3+ years              | Pension award letter, bank statements, Form 1099-R           |
| **Social Security Income**           | Likely to continue    | Social Security award letter, bank statements, Form SSA-1099 |
| **Disability Income**                | 3+ years              | Disability award letter, bank statements                     |
| **Workers' Compensation**            | Likely to continue    | Award letter (may have time limitations)                     |
| **Defined Contribution Plan Income** | Likely to continue    | Account statements, distribution records                     |
| **Retirement Income**                | 3+ years              | Documentation showing continuation from multiple sources     |

**Example:** The borrower receives \$3,000/month from a pension plan. The qualified income is \$3,000/month if the pension award letter confirms continuation for at least 3 years.

See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for retirement and benefits income fields.

### Support and alimony income

Income from court-ordered support payments. All support income types require 3-year continuation documentation.

| Income Type                     | Key Documents                                           | Notes                                |
| ------------------------------- | ------------------------------------------------------- | ------------------------------------ |
| **Alimony Income**              | Divorce decree or separation agreement, bank statements | Must demonstrate 3-year continuation |
| **Child Support Income**        | Court order or agreement, bank statements               | Must demonstrate 3-year continuation |
| **Separate Maintenance Income** | Court order, bank statements                            | Similar to alimony requirements      |

See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for support income fields.

### Employer allowances and benefits

Additional compensation provided by employers beyond base salary.

| Income Type                           | Key Documents                            | Notes                                           |
| ------------------------------------- | ---------------------------------------- | ----------------------------------------------- |
| **Automobile Allowance**              | Employment contracts, pay stubs          | Included if documented and likely to continue   |
| **Housing Allowance**                 | Employment contracts, pay stubs          | Included if documented and likely to continue   |
| **Mortgage Differential Income**      | Employment contracts, benefit statements | Employer mortgage assistance programs           |
| **Employment Related Account Income** | Benefit statements, account records      | Various employer-sponsored accounts or benefits |

See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for employer allowance fields.

### Investment and asset income

Income generated from investments, assets, and financial instruments.

| Income Type                             | Key Documents                         | Notes                                                              |
| --------------------------------------- | ------------------------------------- | ------------------------------------------------------------------ |
| **Royalties Income**                    | Tax returns (Form 1099-MISC)          | Can vary significantly year-to-year; must demonstrate continuation |
| **Trust Income**                        | Trust documents, distribution records | Must demonstrate income will continue                              |
| **Notes Receivable Installment Income** | Loan agreement, payment history       | Income from loans borrower made to others                          |

See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for investment income fields.

### Government and assistance programs

Income from government programs and assistance.

| Income Type                            | Typically Counts    | Key Documents                           | Notes                                           |
| -------------------------------------- | ------------------- | --------------------------------------- | ----------------------------------------------- |
| **Public Assistance Income**           | Varies by program   | Benefit statements                      | Some loan programs don't allow this income type |
| **Housing Choice Voucher (Section 8)** | Yes (if documented) | Voucher documentation, lease agreements | Must demonstrate likely to continue             |
| **VA Benefits Non-Educational**        | Yes                 | VA award letters, benefit statements    | Non-education related VA benefits               |
| **Unemployment Income**                | No                  | N/A                                     | Typically not counted (temporary, not stable)   |
| **Foster Care Income**                 | Yes (if documented) | Contracts, payment records              | Must demonstrate continuation                   |

See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for government program income fields.

### Other income types

Additional income types supported by Pylon.

| Income Type                            | Typically Counts  | Key Documents                            | Notes                                           |
| -------------------------------------- | ----------------- | ---------------------------------------- | ----------------------------------------------- |
| **Temporary Leave Income**             | Yes (paid leave)  | Pay stubs, leave documentation           | Unpaid leave typically doesn't count            |
| **Mortgage Credit Certificate Income** | Yes               | Certificate, tax returns                 | Tax credits that reduce tax liability           |
| **Non-Borrower Contribution Income**   | Varies by program | Documentation of household member income | May have restrictions depending on loan program |
| **Non-Borrower Household Income**      | Varies by program | Documentation of household income        | Similar to non-borrower contribution            |
| **Miscellaneous Income**               | Case-by-case      | Thorough documentation required          | Evaluated individually by lenders               |

Each income type has specific verification requirements and may have different qualification rules. See the [Income GraphQL documentation](https://pylon.mortgage/documentation/graphql/index.html) for complete details on all income types.

## Key concepts to remember

<AccordionGroup>
  <Accordion title="Three income states provide accurate qualification">
    Pylon uses stated, qualified, and verified income to provide accurate
    qualification calculations throughout the loan process. Qualified income
    applies guidelines before documentation is received, giving loan officers
    and borrowers an accurate view of DTI and qualification potential.
  </Accordion>

  <Accordion title="Always check qualified amount before requesting documentation">
    Before requesting documentation, check the `qualifiedAmount` field. If it's
    \$0, documentation won't change the qualification outcome. This saves time
    and money for both borrowers and loan officers.
  </Accordion>

  <Accordion title="Pay period frequency affects monthly calculations">
    Income can be received at various frequencies (weekly, bi-weekly, monthly,
    etc.), and the system properly converts these to monthly amounts for
    qualification calculations. Always provide accurate pay period frequency.
  </Accordion>

  <Accordion title="Different income types have different verification requirements">
    Each income type has specific verification requirements. Familiarize
    yourself with what documentation is needed for each type to set proper
    expectations with borrowers.
  </Accordion>

  <Accordion title="Use the most specific income type available">
    Select the most specific income type available. For example, use
    `MilitaryVariableHousingAllowanceIncome` instead of `MiscellaneousIncome` for
    military housing allowances. This ensures accurate qualification and proper
    guideline application.
  </Accordion>

  <Accordion title="Multiple income sources are combined for qualification">
    When a borrower has multiple income sources, all incomes are created
    separately and combined for total qualification. Each income type is
    evaluated independently against guidelines.
  </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 incomes and are evaluated for qualification.
* **Employment** - Employment details associated with employment income.
* **OwnedProperty** - Properties owned by borrowers that may generate rental income.
* **LoanApplication** - The loan application that contains the borrower's incomes.