---
title: "Calculate Fannie Mae self-employed income"
method: POST
path: "/v2/book/{book_uuid}/income/self-employed/calculate"
tags: ["Income"]
---

# Calculate Fannie Mae self-employed income

`POST /v2/book/{book_uuid}/income/self-employed/calculate`

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](#organization-level-defaults) 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](https://docs.ocrolus.com/reference/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).

| Category | Merge behavior |
|---|---|
| Top-level meta fields such as `employment_start_date` | Provided values overwrite existing values. Fields not included in the request are preserved. |
| Common `yearwise_details` | Merged by `year`. Only the fields provided for a given year are updated. |
| Per-type `yearwise_details` such as `s_corporation_earnings.yearwise_details` | Merged by `year`. Existing fields are preserved unless explicitly overridden. |

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

| Category | Field location | Fallback condition |
|---|---|---|
| Common scalar | `meta_info.field` | Applied when the value is `null` or an empty list `[]` |
| Common yearwise | `meta_info.yearwise_details[].field` | Applied per year when the field value is `null` or `""` |
| Per-type yearwise | `meta_info.<type>.yearwise_details[].field` | Applied to each active tax year when the field value is `null` or `""` |

### Supported default fields
| Category                      | Supported Fields                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Common defaults**           | `employment_start_date`, `employment_history_consistent_indicator`, `du_case_file_id`, `extraordinary_one_time_expense`, `non_deductible_meal`                                                                                                                                                                                                         |
| **Per-type defaults**         | Supported under `s_corporation_earnings`, `partnership_income`, `regular_corporation`, and `individual_tax_return`.                                                                                                                                                                                                                                    |
| **Per-type supported fields** | `adequate_business_liquidity`, `amortization`, `amortization_selection_type`, `is_final_return_override`, `is_borrower_trust_guaranter`, `compensation_of_officers_included_as_income`, `mortgages_notes_and_bonds_payable_less_than1_year`, `mortgages_notes_and_bonds_payable_less_than1_year_amount`, `guaranteed_payments_to_partners_alternative` |

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.

## Path parameters

- `book_uuid` string, uuid, required

## Request body

- object
  - `borrower_uuid` string, uuid — The unique identifier of the borrower for whom self-employed income is being calculated.
  - `business_uuid` string, uuid — The unique identifier of the business associated with the borrower for which self-employed income is being calculated.
  - `income_guideline` 'FANNIE_MAE' | 'FANNIE_MAE_RECOMMENDED' — The guideline to be used for calculating the self-employed income. Supported values include FANNIE_MAE and FANNIE_MAE_RECOMMENDED.
  - `meta_info` object — Contains metadata fields used during income recalculation. Provided fields are merged with the existing income record before recalculation. If a field is missing or empty, organization-level defaults may be applied. Defaults act as fallback values and do not override explicitly provided values. It can include: - **Common fields** applied across all tax return types. - **Per tax return-specific fields** applied to individual tax return types. The following objects contain fields specific to each tax return type: - `s_corporation_earnings` - `partnership_income` - `regular_corporation` - `individual_tax_return`
    - `employment_start_date` string, nullable — Employment start date in ISO format, for example, `2020-01-15`.
    - `employment_history_consistent_indicator` boolean — Indicates whether employment history is consistent.
    - `du_case_file_id` string, nullable — DU case file identifier.
    - `yearwise_details` object[] — Per-year common details.
      - `year` integer, required — Tax year, for example, `2023`.
      - `is_selected` boolean, required — Indicates whether this year is selected for calculation.
      - `extraordinary_one_time_expense` number, nullable — Extraordinary one-time expense amount.
      - `non_deductible_meal` number, nullable — Non-deductible meal expense amount.
    - `s_corporation_earnings` object — Per-tax-return-type meta fields for S-Corporation earnings.
      - `yearwise_details` object[]
        - `year` integer, required — Tax year.
        - `is_selected` boolean — Indicates whether this year is selected.
        - `adequate_business_liquidity` boolean, nullable — Indicates whether the business has adequate liquidity.
        - `compensation_of_officers_included_as_income` boolean, nullable — Indicates whether officer compensation is included as income.
        - `mortgages_notes_and_bonds_payable_less_than1_year` 'All' | 'None' | 'Some', nullable — Mortgages, notes, and bonds payable in less than 1 year.
        - `mortgages_notes_and_bonds_payable_less_than1_year_amount` number, nullable — Amount when `Some` is selected.
        - `is_borrower_trust_guaranter` '1' | '2' | '3', nullable — Indicates whether the borrower is a trust guarantor. Allowed values are - `1` = Yes, `2` = No, `3` = None.
        - `amortization` number, nullable — Amortization amount.
        - `amortization_selection_type` '1' | '2' | '3' — Amortization selection type. Allowed values are - `1` = Yes, `2` = No, `3` = None.
        - `is_final_return_override` boolean, nullable — Indicates whether final return override is applied.
    - `partnership_income` object — Per-tax-return-type meta fields for partnership income.
      - `yearwise_details` object[]
        - `year` integer, required — Tax year.
        - `is_selected` boolean — Indicates whether this year is selected.
        - `adequate_business_liquidity` boolean, nullable — Indicates whether the business has adequate liquidity.
        - `mortgages_notes_and_bonds_payable_less_than1_year` 'All' | 'None' | 'Some', nullable — Mortgages, notes, and bonds payable in less than 1 year.
        - `mortgages_notes_and_bonds_payable_less_than1_year_amount` number, nullable — Amount when `Some` is selected.
        - `is_borrower_trust_guaranter` '1' | '2' | '3', nullable — Indicates whether the borrower is a trust guarantor. Allowed values are - `1` = Yes, `2` = No, `3` = None.
        - `amortization` number, nullable — Amortization amount.
        - `amortization_selection_type` '1' | '2' | '3' — Amortization selection type. Allowed values - `1` = Yes, `2` = No, `3` = None.
        - `is_final_return_override` boolean, nullable — Indicates whether final return override is applied.
        - `guaranteed_payments_to_partners_alternative` boolean, nullable — Indicates whether the guaranteed payments to partners alternative applies.
    - `regular_corporation` object — Per-tax-return-type meta fields for regular corporation.
      - `yearwise_details` object[]
        - `year` integer, required — Tax year.
        - `is_selected` boolean — Indicates whether this year is selected.
        - `column_a_officers_count` integer, nullable — Number of Column A officers.
        - `borrower_ownership_more_than25_pct` boolean, nullable — Indicates whether the borrower owns more than 25%.
        - `all_officers_of_column_a_are_borrowers` integer, nullable — Indicates whether all Column A officers are borrowers.
        - `form1125e_included` boolean, nullable — Indicates whether Form 1125-E is included.
        - `compensation_of_officers_included_as_income` boolean, nullable — Indicates whether officer compensation is included as income.
        - `amortization` number, nullable — Amortization amount.
        - `amortization_selection_type` '1' | '2' | '3' — Amortization selection type. Allowed values are - `1` = Yes, `2` = No, `3` = None.
        - `is_final_return_override` boolean, nullable — Indicates whether final return override is applied.
    - `individual_tax_return` object — Per-tax-return-type meta fields for individual tax return.
      - `yearwise_details` object[]
        - `year` integer, required — Tax year.
        - `is_selected` boolean — Indicates whether this year is selected.
        - `non_deductible_meal` number, nullable — Non-deductible meal amount for this year.

## Response `200`

Success

- object
  - `response` object — Contains the detailed of recalculated self-employed income.
    - `book_uuid` string, uuid — Unique identifier for the income Book from the income is calculated.
    - `borrower_uuid` string, uuid — Unique identifier of the borrower for whom self-employed income is calculated.
    - `business_uuid` string, uuid — Unique identifier of the business for whom self-employed income is calculated.
    - `income_guideline` string — Income calculation guideline that was used to calculate income.
    - `status` string — Status of the income calculation.

## Other responses

- `400` — Missing request body, identifiers, meta_info or invalid Auth and income guideline
- `404` — No existing income
- `500` — Internal server error

---

[API](https://skmtc.net/ocrolus/apis/user-management.md) · [All operations](https://skmtc.net/ocrolus/apis/user-management/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ocrolus/user-management/revisions/3571ef602d13/schema)