WorkflowResidential Mortgage & Home Equity Origination

Self-Employed Income Calculation · integration

Fannie Mae Income Calculator API: what to put around it

Fannie Mae's Income Calculator is reached by web, by import file or through an approved technology provider's integration, and it is worth keeping for the relief it gives. It calculates only what it is sent, one borrower and business at a time, under Fannie policy. Here is what to build before and after it, and where Botminds' Self-Employed Income Calculation fits.

Updated · 13 min read

See one case, screen by screen →
Watch with transcript →

The Fannie Mae Income Calculator can be used three ways: in its free web interface, by importing a pre-defined data file, or through an integrated connection run by a Fannie Mae-approved technology service provider, which is what most people searching for a "Fannie Mae Income Calculator API" are after. Whichever way, it does one thing well: it applies Fannie's Selling Guide to tax-return figures and returns a qualifying income and a findings report, and if the lender uses no more than that figure and meets the conditions, Fannie offers relief from representations and warranties on the calculation. Everything around that is the lender's: getting the right figures in, checking them against the IRS, deciding what recurs, documenting a decline, and covering FHA and VA files the calculator does not apply. Botminds' Self-Employed Income Calculation is a set of agents that does that surrounding work. This page maps what the calculator takes and returns, and what to put on each side of it.

Around the Income Calculator: what sits before it, in it and after it

The layers around Fannie Mae's Income CalculatorFive layers from top to bottom. One: the documents, meaning personal and business returns, K-1s, the profit and loss statement and IRS transcripts. Two: before the calculator, the lender's side, read and cite every line, match each return to its transcript, decide what recurs, and pick the program. Three: Fannie Mae's Income Calculator, one evaluation per borrower and business, returning a qualifying income and a findings report, with relief when the lender's figure is not more than the calculator's. Four: after the calculator, compare the lender's figure with the calculator's, answer its messages, write conditions and resubmit to Desktop Underwriter. Five: the underwriter signs, with the findings report kept in the loan file.1 · Documents in1040s and schedules, 1065 / 1120-S /1120, K-1s, P&L, IRS transcriptslender2 · Before the calculatorRead and cite every line usedMatch each return to its transcriptFlag one-time items for a personRoute FHA and VA files elsewhereagents3 · Fannie Mae Income CalculatorOne evaluation per borrowerand business; figures as enteredReturns: income, findings reportRelief if lender figure ≤ its figure4 · After the calculatorCompare your figure with its figureAnswer its messages; write conditionsResubmit DU at the signed incomeagents5 · The underwriter signsFindings report and written analysiskept in the loan fileperson
Our reference design. The calculator layer is Fannie Mae's; the layers above and below are the lender's responsibility under the Selling Guide, whoever performs them. Connecting agents to the calculator runs through a Fannie Mae-approved technology service provider.Source: Fannie Mae, Income Calculator user guide (November 2024); Selling Guide B3-3.1-03

Does the Fannie Mae Income Calculator have an API?

It has integrated access, offered through approved providers rather than as a public developer service. Fannie's user guide describes a free web interface and an import option, and refers to evaluations "submitted via an integrated service" and to "an integrated connection with an authorized technology service provider (TSP)"; evaluations created that way "cannot be managed using the Fannie Mae web interface", and their updates "must be handled through the TSP" (Income Calculator user guide). So a lender that wants the calculator inside its own systems usually reaches it through a provider on Fannie's approved list, often the same company that supplies its document reading or its origination system. Ask Fannie Mae or the provider for the current specification; it is not part of the Selling Guide.

The import route is the plainer one. A user can start an evaluation by uploading "a pre-defined data file", but the calculator "does not support the import of tax return PDF files". Something has to turn the returns into that data first, and that something is where most of the integration work and most of the risk sit.

Fannie Mae's Income Calculator in three numbers

$0

to use the web interface; no login is required

1

evaluation per borrower and business, and one per rental property

0

tax return PDFs it will import; figures arrive keyed or as a data file

Source: Fannie Mae, Income Calculator Web Interface User Guide, November 2024

What is a Fannie Mae-approved technology service provider?

It is a company Fannie Mae has approved to extract tax-return data and populate the calculator's fields for a lender. The Selling Guide allows a lender to use one for exactly that purpose (B3-3.1-03). Approval covers the connection, not the lender's duty. The Selling Guide still makes the lender ensure that everything submitted is "accurate, complete, and reflects the information on the tax returns being used", and to "investigate and resolve any contradictory or conflicting information that may impact the accuracy of the income calculation" (B3-3.1-03).

That makes the provider part of the lender's vendor oversight. Since Fannie Mae's Lender Letter LL-2026-04 took effect, a seller that uses AI or machine learning in origination must manage its vendors' use of AI under policies "no less protective" than its own and disclose the types and purposes of AI it uses when Fannie asks (LL-2026-04). If the provider's extraction uses machine learning, it falls inside that.

What the calculator does with what you send it

It runs Fannie's cash-flow method business by business and explains itself. Each evaluation is one borrower and one business; a borrower with two businesses needs two, and the calculator "does not consider other Income Calculator evaluations when generating its findings". It asks for the employment start date, which must match what was given to Desktop Underwriter, the business structure, which years have been filed and which forms are in hand.

The findings report shows the figures the user entered beside the figures it used, the monthly qualifying income, a comparative income analysis labelled "Increasing", "Level" or "Declining", and a liquidity analysis using distributions, the quick ratio and the current ratio. Messages fall into four groups: risk and eligibility, data integrity, verifications and conditions, and observations. A "Declining" trend produces a message that the file must show the income has stabilized before it is used; the treatment of declines is compared with FHA's in FHA self-employed income decline against Fannie's trend test.

What the calculator leaves to the lender

It leaves everything that requires looking at documents or making a judgement. Users are told to enter figures "exactly as it appears on the tax return form" and not to adjust them "based on underwriting assessments, such as whether an income or loss amount is recurring or nonrecurring". It holds no borrower names or employer numbers and never sees the returns, so it cannot confirm that the numbers came from them; the lender "remains responsible for the data's integrity (ensuring the data was transcribed correctly from the tax returns to Income Calculator)" (Income Calculator user guide).

Who does what around the Income Calculator

TaskIncome CalculatorLender (people or agents)
Read the returns and find each figureNoYes: page and line for each figure
Check returns against IRS transcriptsNoYes: a transcript received before closing must be used to verify
Apply Fannie Mae’s cash-flow methodYesYes, to check its figure or for files it does not take
Decide whether an item recursNo: takes figures as filedYes, in writing
Trend and liquidity analysisYes, with messagesAnswers the messages; documents a stabilized decline
FHA and VA methodsNoYes: HUD Handbook 4000.1, VA rules
Rental income on business returnsNot yet supportedYes
Link to the DU casefile before deliveryHolds the linkMakes it; required for relief
Sign the incomeNoThe underwriter
From Fannie Mae's Income Calculator user guide and Selling Guide B3-3.1-02 and B3-3.1-03. Our summary in plain words.Source: Income Calculator user guide; Selling Guide B3-3.1-02

Does the Income Calculator work for FHA or VA loans?

No. It calculates income "consistent with Fannie Mae Selling Guide policy", and FHA's rules differ in ways that change the answer. HUD requires the lesser of the two-year and one-year averages of self-employment income, a manual underwrite when business income falls more than 20% over the analysis period, and a year-to-date profit and loss statement once more than a calendar quarter has passed since the last tax year (HUD Handbook 4000.1). A lender with FHA or VA volume needs another method for those files, and a way to keep the two from drifting apart in practice. Botminds' Self-Employed Income Calculation applies the HUD Handbook method to FHA files and the VA Lenders Handbook to VA files, and shows the Form 1084 and Form 91 methods side by side on conventional files.

Where agents sit: before, beside and after the calculator

Before it, agents turn documents into cited figures; after it, they check the answer against the file. Before: the return reader extracts each line with its year, page and line; the transcript matcher compares each return with the IRS transcript, which Fannie requires a lender to use for verification when it arrives before closing (B3-3.1-02); the cash-flow calculator builds the worksheet under the program's rules, flagging items such as a one-time equipment gain for a person to confirm. Transcripts themselves come through the IRS's verification service at $4 each (IRS IVES).

After: the lender's figure is compared with the calculator's, because relief depends on the lender using no more than the calculator's amount (A2-2-04). The decision writer recomputes DTI and prepares the resubmission to Desktop Underwriter, which matters because the calculator "does not overwrite any DU submission data" and DU itself "does not generate any messages related to Income Calculator". If the income cannot be shown to be stable, Fannie's rule is plain: the income must be removed and the loan resubmitted (B3-3.1-01).

One self-employed conventional file, with the calculator in the middle

  1. Agent

    Return reader

    Extracts every line used for income from the returns, with year, page and line.

    Never: Never infers a figure not on the page.

  2. Agent

    Transcript matcher

    Matches each return to its IRS transcript; a year with no record becomes a condition.

    Never: Never accepts a year without a transcript or proof of filing.

  3. Agent

    Cash-flow calculator

    Builds Form 1084 and the lender’s comparison method; marks items that need a recurring or one-time decision.

  4. A person decides

    Underwriter

    Confirms what recurs and which figures go to the calculator.

  5. Agent

    Approved provider connection

    Sends the figures to Fannie Mae’s Income Calculator and returns its income and findings report.

  6. Agent

    Conditions and decision writer

    Compares figures, answers messages with conditions, recomputes DTI and prepares the DU resubmission.

    Never: Never signs.

  7. A person decides

    Underwriter

    Signs the qualifying income; the findings report and written analysis go in the loan file.

Our reference sequence. The provider connection is Fannie Mae's approved route to the calculator; the agent and person steps are those of Botminds' Self-Employed Income Calculation.

The decision side: figures by source, DTI and the resubmission

The Castellano income decision screen. Qualifying monthly income by source: Daniel $18,300.00 using 2025 only after an 8.9% decline, Lena $4,532.79 two-year average, rental $81.33, total $22,914.12; the Form 91 method $21,414.12; the estimate at application $24,222.17 and a difference of minus $1,308.05. DTI 33.78% at application and 35.71% with the worksheet; automated findings marked Resubmit. On the right, a checklist of findings reviewed, a Sign income button and a drafted note to the loan officer.
Fictional sample data. The decision writer lists income by source and the comparison figures, recomputes DTI and prepares the resubmission; nothing is sent until the underwriter signs.

Can I integrate the Income Calculator with my LOS?

Yes, through an approved provider, and the design questions are about data, not screens. Decide which system is the source of truth for the income: the calculator, your worksheet or your origination system. Decide how the calculator's evaluation ID is stored against the loan, since the web interface has "limited case management functionality" and the ID is how an evaluation is found again. Decide who links the evaluation to the DU casefile before delivery, which relief requires, and how a change after the link, such as a corrected K-1, is handled.

Plan for the files it cannot take as well: FHA and VA loans, rentals reported on business returns, and any income the lender decides to calculate more conservatively than the calculator. For those, the written analysis must still meet the standard of Form 1084 (B3-3.5-01). The broader choice between methods is compared in tax return analysis software against a spreadsheet and the Income Calculator.

Eight decisions to make before connecting the Income Calculator

  1. Which provider, and what it extracts

    Confirm it is on Fannie Mae’s approved list and how it reads your documents.

  2. Where the evaluation ID lives

    Store it on the loan; without it, finding the evaluation again depends on challenge questions.

  3. Who links the DU casefile

    Relief needs the link before delivery; make it a named step.

  4. What the calculator is not sent

    FHA, VA and business-return rentals need your own method and written analysis.

  5. How recurring items are decided

    The calculator takes figures as filed; your underwriter decides what recurs.

  6. How transcripts are checked

    Before figures go in, each year used should agree with the IRS or carry a condition.

  7. Which figure is used

    If your figure is higher than the calculator’s, relief is lost; decide who may choose that.

  8. How the provider’s AI is governed

    LL-2026-04 brings vendor AI under your policies and your annual review.

Our checklist, from the Income Calculator user guide, Selling Guide B3-3.1-03 and A2-2-04, and Lender Letter LL-2026-04.

Questions people ask

What is the Income Calculator findings report?

It is the calculator's output: the monthly qualifying income for which Fannie Mae offers relief, the entered and used figures side by side, the trend and liquidity analyses and its messages. Fannie accepts it in place of a written analysis on Form 1084 or Form 1088, and a copy must be kept in the loan file.

Does the calculator give rep and warrant relief?

Yes, on the accuracy of the income calculation, income source by income source, when the inputs are accurate and complete, the findings report is in the file, the income used is not more than the calculator's and the evaluation is linked to the DU casefile before delivery. It does not cover the accuracy of the data the lender entered.

Can the Income Calculator read tax return PDFs?

No. Figures are keyed in the web interface or arrive in a pre-defined import file or through an approved provider's integration. Turning the PDFs into those figures, and checking them against the returns and the IRS, is the lender's job.

Is the Income Calculator required?

No. It is optional; a lender may use Form 1084, another cash-flow analysis that applies the same principles, or an approved vendor tool. The calculator, and approved vendor tools under their own conditions, are the routes that bring representation and warranty relief on the calculation.

Does Freddie Mac have the same thing?

Freddie Mac has its own cash-flow worksheet, Form 91, and its own Seller/Servicer Guide, and lenders selling to it work to Freddie's terms. Nothing in Fannie Mae's relief carries over to a loan sold to Freddie, so treat each enterprise's requirements separately and keep a written analysis that meets the one you deliver to.

Self-Employed Income Calculation.
See it on your own files.

An agentic solution from Botminds. Tax returns in, a qualifying income worksheet out, every figure tied to its line on the return. Book a demo, or explore how it works.