Skip to main content

​
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:
  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 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 calculations if documentation hasn’t been received yet. This creates a poor borrower experience because it shows an inflated 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 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, requiring borrower opt-in either through an embedded widget (Truv Bridge, in-flow) or a hosted link you request and send to the borrower (out-of-flow)
    • 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 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 for field details.

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

​
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. 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 for all military income types.

​
Rental and property income

Income generated from real estate properties owned by the borrower. 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 and OwnedProperty documentation for details.

​
Retirement and benefits income

Income from retirement plans, government benefits, and disability programs. 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 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. See the Income GraphQL documentation for support income fields.

​
Employer allowances and benefits

Additional compensation provided by employers beyond base salary. See the Income GraphQL documentation for employer allowance fields.

​
Investment and asset income

Income generated from investments, assets, and financial instruments. See the Income GraphQL documentation for investment income fields.

​
Government and assistance programs

Income from government programs and assistance. See the Income GraphQL documentation for government program income fields.

​
Other income types

Additional income types supported by Pylon. Each income type has specific verification requirements and may have different qualification rules. See the Income GraphQL documentation for complete details on all income types.

​
Key concepts to remember

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.
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.
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.
Each income type has specific verification requirements. Familiarize yourself with what documentation is needed for each type to set proper expectations with borrowers.
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.
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.
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.