---
title: "Income calculations"
method: GET
path: "/v2/book/{book_uuid}/income-calculations"
tags: ["Income"]
---

# Income calculations

`GET /v2/book/{book_uuid}/income-calculations`

This API provides income values based on the specified guidelines for a <<glossary:Book>> type. The supported income types include `wage-earner`, `self-employed`, `rental`, and `other income`. A detailed description of income-related fields found in the `calculated_fields` objects within the totals array can be found in the [income calculation](https://docs.ocrolus.com/docs/income-calculations-api) definition. These fields include attributes like field name, default value, and title/header to identify and interpret each data point.
  
> 👍 Tips
> To retrieve Fannie Mae income calculation data, first call the [Fannie Mae self-employed income calculation](https://docs.ocrolus.com/reference/self-employed-income-calculation-fm) API, and then call the this income calculation API.

## Path parameters

- `book_uuid` string, uuid, required

## Query parameters

- `guideline` 'FANNIE_MAE' | 'FREDDIE_MAC' | 'FHA' | 'VA' | 'USDA'

## Response `200`

Success

- object
  - `response` object — Contains the detailed income calculations and related data.
    - `book_uuid` string, uuid — Unique identifier for the income calculation <<glossary:Book>>.
    - `incomes` object[] — List of the borrower's income sources used for calculations.
      - `borrower_uuid` string, uuid — Unique identifier of the borrower.
      - `business_uuid` string, uuid — Unique identifier for the business (if applicable).
      - `income_type` 'OTHER' | 'SELF_EMPLOYED' | 'WAGE_EARNER' | 'RENTAL' — Type of income. The available income types are -
      - `year` string — Year of the income calculation.
      - `forms` object[] — List of forms associated with the income calculation.
        - `form_type` string — Type of the form.
        - `form_uuid` string, uuid — Unique identifier for the form.
        - `mixed_uploaded_doc_pk` string — Primary key (PK) of the mixed uploaded document.
        - `uploaded_doc_pk` string — Primary key of the uploaded document.
        - `page_doc_pks` string[] — List of page document PKs.
      - `fields` object[] — List of fields and their values for the income calculation.
        - `name` string — Name of the field.
        - `value` string — Value of the field.
        - `title` string — Title or description of the field.
        - `page_doc_pk` string — Primary key of the page document (if applicable).
      - `calculated_fields` object[] — List of calculated fields and their values.
        - `name` string — Name of the calculated field.
        - `value` string — Value of the calculated field.
        - `title` string — Title or description of the calculated field.
      - `currency` string — Currency used for the income calculation.
      - `income_by_tax_returns` 'IRS Form 1040 - Individual Income Tax Return' | 'IRS Form 1065 - Partnership Income' | 'IRS Form 1120 - Regular Corporation' | 'IRS Form 1120S - S Corporation Earnings' — IRS tax form used to report the income. The available forms are -
      - `xid` string — A unique identifier for the borrower/employer pair.
      - `pay_type` 'Bonus Income' | 'Commission Income' | 'Hourly Income' | 'Military Income' | 'Misc Income' | 'Overtime Income' | 'Salary Income' | 'Shift Differential Income' — Pay type available for the wage earner income type. The available pay types are -
      - `other_income_collection` 'Accessory unit income' | 'Alimony' | 'Automobile allowance' | 'Boarder income' | 'Capital gains' | 'Child support' | 'Defined contribution plan' | 'Disability' | 'Employment related account' | 'Foster care' | 'Housing allowance' | 'Housing choice voucher program' | 'Interest / Dividend' | 'Mortgage credit certificate' | 'Mortgage differential' | 'Non borrower household income' | 'Notes receivable installment' | 'Other' | 'Public assistance' | 'Retirement/Pension/Annuity' | 'Royalty' | 'Separate maintenance' | 'Social security' | 'Temporary leave' | 'Tip income' | 'Trust' | 'Unemployment Income' | 'VA benefits non-educational' — Additional income sources not listed in standard income types. The available income types are -
      - `hourly_rate` string — Hourly rate of the income source.
      - `hours_worked_per_week` string — Number of hours worked per week.
      - `monthly_income` string — Monthly income of the income source.
      - `period_earnings` string — Earnings for the specified period.
      - `pay_frequency` string — Frequency of pay (e.g., Weekly, Bi-Weekly, Monthly).
      - `is_active` boolean — Indicates whether this income source is currently active.
      - `is_selected` boolean — Indicates whether this income source is selected.
    - `borrowers` object[] — List of borrowers associated with the income calculations.
      - `uuid` string, uuid — Unique identifier for the borrower.
      - `name` string — Name of the borrower.
    - `employers` object[] — List of employers associated with the income calculations.
      - `uuid` string, uuid — Unique identifier for the employer.
      - `name` string — Name of the employer.
    - `properties` object[] — List of properties associated with the income calculations.
      - `uuid` string, uuid — Unique identifier for the property.
      - `address` string — Address of the property.
      - `address_line1` string — First line of the property's address.
      - `city` string — City where the property is located.
      - `state` string — State where the property is located.
      - `postal_code` string — Postal code of the property's address.
    - `alerts` object[] — List of alerts related to the income calculations.
      - `message` string — Alert message.
      - `severity` string — Severity level of the alert.
      - `income_type` string — Type of income associated with the alert.
    - `totals` object[] — List of total calculated fields for each borrower's income type and business.
      - `borrower_uuid` string, uuid — Unique identifier of the borrower.
      - `income_type` string — Type of income (e.g., WAGE_EARNER, SELF_EMPLOYED, OTHER).
      - `business_uuid` string, uuid — Unique identifier for the business (if applicable).
      - `calculated_fields` object[] — List of calculated fields and their values for the total.
        - `name` string — Name of the calculated field.
        - `value` string — Value of the calculated field.
        - `title` string — Title of the calculated field.

## Other responses

- `400` — Client Errors
- `404` — Client Errors

---

[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)