Calculate Fannie Mae self-employed income

This API calculates Fannie Mae self-employed income for a borrower–business pair in a Book. Send only the fields you want to update. The API merges these fields with the existing income record and recalculates the income. If a field is missing or empty, the system may apply organization-level default values based on the income type and guideline. These defaults act as fallback values and never override fields explicitly provided in the request.

👍 Tips After calling this API, call the Income calculations API to retrieve the updated income data.

Merge behavior

The API performs a deep merge of the provided meta_info into the existing income record (common or tax-return specific).

Organization-level defaults

Organizations can configure default values for self-employed income fields by org_uuid, income_type, and income_guideline.

Defaults act as fallback values during income updates. They are applied only when a supported field is missing or empty in the request. Explicit values, including false, 0, and None, are never overridden.

Default application rules

Supported default fields

Per-type defaults are stored as flat key-value pairs in org config and are replicated into each active tax year's yearwise_details during update.

{
  "borrower_uuid": "11111111-1111-1111-1111-111111111111",
  "business_uuid": "22222222-2222-2222-2222-222222222222",
  "income_guideline": "FANNIE_MAE_RECOMMENDED",
  "meta_info": {
    "employment_start_date": "2020-01-15",
    "employment_history_consistent_indicator": true,
    "du_case_file_id": "DU-12345",
    "yearwise_details": [
      {
        "year": 2023,
        "is_selected": true,
        "extraordinary_one_time_expense": 1000,
        "non_deductible_meal": 200
      },
      {
        "year": 2022,
        "is_selected": false,
        "extraordinary_one_time_expense": null,
        "non_deductible_meal": 150
      }
    ],
    "s_corporation_earnings": {
      "yearwise_details": [
        {
          "year": 2023,
          "is_selected": true,
          "adequate_business_liquidity": true,
          "compensation_of_officers_included_as_income": false,
          "mortgages_notes_and_bonds_payable_less_than1_year": "Some",
          "mortgages_notes_and_bonds_payable_less_than1_year_amount": 15000,
          "is_borrower_trust_guaranter": "2",
          "amortization": 500,
          "amortization_selection_type": "1",
          "is_final_return_override": false
        },
        {
          "year": 2022,
          "is_selected": false,
          "adequate_business_liquidity": null,
          "compensation_of_officers_included_as_income": true,
          "mortgages_notes_and_bonds_payable_less_than1_year": "None",
          "mortgages_notes_and_bonds_payable_less_than1_year_amount": null,
          "is_borrower_trust_guaranter": "3",
          "amortization": null,
          "amortization_selection_type": "3",
          "is_final_return_override": null
        }
      ]
    },
    "partnership_income": {
      "yearwise_details": [
        {
          "year": 2023,
          "is_selected": true,
          "adequate_business_liquidity": false,
          "mortgages_notes_and_bonds_payable_less_than1_year": "All",
          "mortgages_notes_and_bonds_payable_less_than1_year_amount": null,
          "is_borrower_trust_guaranter": "1",
          "amortization": 300,
          "amortization_selection_type": "2",
          "is_final_return_override": true,
          "guaranteed_payments_to_partners_alternative": true
        },
        {
          "year": 2022,
          "is_selected": false,
          "adequate_business_liquidity": true,
          "mortgages_notes_and_bonds_payable_less_than1_year": "Some",
          "mortgages_notes_and_bonds_payable_less_than1_year_amount": 8000,
          "is_borrower_trust_guaranter": "2",
          "amortization": 200,
          "amortization_selection_type": "1",
          "is_final_return_override": false,
          "guaranteed_payments_to_partners_alternative": null
        }
      ]
    },
    "regular_corporation": {
      "yearwise_details": [
        {
          "year": 2023,
          "is_selected": true,
          "column_a_officers_count": 3,
          "borrower_ownership_more_than25_pct": true,
          "all_officers_of_column_a_are_borrowers": 1,
          "form1125e_included": true,
          "compensation_of_officers_included_as_income": false,
          "amortization": 1200,
          "amortization_selection_type": "1",
          "is_final_return_override": false
        },
        {
          "year": 2022,
          "is_selected": false,
          "column_a_officers_count": null,
          "borrower_ownership_more_than25_pct": false,
          "all_officers_of_column_a_are_borrowers": 0,
          "form1125e_included": false,
          "compensation_of_officers_included_as_income": true,
          "amortization": null,
          "amortization_selection_type": "3",
          "is_final_return_override": null
        }
      ]
    },
    "individual_tax_return": {
      "yearwise_details": [
        {
          "year": 2023,
          "is_selected": true,
          "non_deductible_meal": 250
        },
        {
          "year": 2022,
          "is_selected": false,
          "non_deductible_meal": null
        }
      ]
    }
  }
}

{
  "response": {
    "book_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "borrower_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "business_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "income_guideline": "FANNIE_MAE_RECOMMENDED",
    "status": "success"
  }
}