What is an Income?
An Income represents a source of revenue that a borrower receives, which is used to calculate debt-to-income (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:- 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.
- 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 and qualification potential.
- Comprehensive Income Types - The system supports dozens of income types, from standard employment to specialized military allowances, rental income, retirement benefits, and more.
- Verification Requirements - Different income types have different verification requirements, and the system tracks what documentation is needed for each.
- 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
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:- Taking the stated income
- Applying all relevant mortgage guidelines (Fannie Mae, Freddie Mac, FHA, VA, USDA, etc.)
- Calculating what the income would qualify as if documentation were to support it
- 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)
Verified income
Verified income is the final, documentation-backed amount that has been:- Proven through documentation (W-2s, pay stubs, tax returns, bank statements, etc.)
- Validated against mortgage guidelines
- Confirmed through automated verification integrations (Day 1 Certainty, Automated Income Model, etc.)
verifiedAmount field on an Income entity indicates whether income has been verified:
verifiedAmountisnull: Income has not been verified yet, or verification is not available. The income amount shown instatedAmountorstatedMonthlyAmountis what the borrower stated, but it hasn’t been verified.verifiedAmounthas 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:-
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
verifiedAmountfield is automatically populated, and no additional documentation is typically required - See the Income Verification guide for complete details on how these integrations work, including setup, workflows, and best practices
-
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
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 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 | |
| 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, thestatedAmount and payPeriodFrequency fields are used to calculate monthly income. The employment field contains employer information and start date. See the Income GraphQL documentation 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.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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
Key concepts to remember
Three income states provide accurate qualification
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.
Always check qualified amount before requesting documentation
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.Pay period frequency affects monthly calculations
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.
Different income types have different verification requirements
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.
Use the most specific income type available
Use the most specific income type available
Select the most specific income type available. For example, use
MilitaryVariableHousingAllowance instead of MiscellaneousIncome for
military housing allowances. This ensures accurate qualification and proper
guideline application.Multiple income sources are combined for qualification
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.
Related entities
For more information on related entities, see the GraphQL API Reference:- 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.