Ocrolus Income API
The Income API from Ocrolus — 5 operation(s) for income.
OpenAPI Specification
openapi: 3.0.0
info:
title: Account Level Webhooks Book Commands Income API
version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: Income
paths:
/v2/book/{book_uuid}/income/summary:
get:
summary: Income summary
operationId: income-summary
tags:
- Income
description: Retrieve a summarized view of income data for a specific <<glossary:Book>> in Ocrolus.
parameters:
- name: book_uuid
in: path
required: true
description: The unique identifier of the <<glossary:Book>> from which the income summary is retrieved.
schema:
type: string
format: uuid
example: 13e6d579-4699-43e2-a419-8a29bcb5f922
- name: guideline
in: query
required: false
description: 'The guideline to be used for retrieving the income summary. Supported values include FANNIE_MAE, FREDDIE_MAC, FHA, VA, and USDA.
'
schema:
type: string
example: FANNIE_MAE
default: FANNIE_MAE
enum:
- FANNIE_MAE
- FREDDIE_MAC
- FHA
- VA
- USDA
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
title: Success
type: object
properties:
response:
type: object
properties:
book_uuid:
type: string
format: uuid
example: 13e6d579-4699-43e2-a419-8a29bcb5f922
description: Unique identification code of a <<glossary:Book>>.
income_summary_data:
type: array
items:
type: object
properties:
borrower_uuid:
type: string
format: uuid
example: 8e52e9b6-6254-45a7-b008-1cebb825cfed
description: Unique identification code of the borrower.
borrower_name:
type: string
example: JILL SMITH
description: Name of the borrower.
wage_earner_income:
type: object
properties:
is_income_calculated:
type: boolean
example: true
description: Indicates if the wage earner income is calculated.
is_empty:
type: boolean
example: true
description: Indicates if the wage earner income is empty.
total_income:
type: number
format: float
example: 0
description: Total wage earner income.
alerts:
type: array
items:
type: object
properties:
message:
type: string
example: Choose the default income type on wage earner tab to see the correct total income for JOHN SAMPLE.
description: Alert message.
severity:
type: string
example: HIGH.
description: Severity of the alert.
example: Choose the default income type on wage earner tab to see the correct total income for JOHN SAMPLE.
description: List of alerts related to wage earner income.
self_employed_income:
type: object
properties:
is_income_calculated:
type: boolean
example: true
description: Indicates if the self-employed income is calculated.
is_empty:
type: boolean
example: false
description: Indicates if the self-employed income is empty.
total_income:
type: number
format: float
example: 9374.429166666667
description: Total self-employed income.
alerts:
type: array
items:
type: object
properties:
message:
type: string
example: Choose the default income type on self employed income tab to see the correct total income for JOHN SAMPLE.
description: Alert message.
severity:
type: string
example: HIGH.
description: Severity of the alert.
example: []
description: List of alerts related to self-employed income.
rental_income:
type: object
properties:
is_income_calculated:
type: boolean
example: true
description: Indicates if the rental income is calculated.
is_empty:
type: boolean
example: false
description: Indicates if the rental income is empty.
total_income:
type: number
format: float
example: 359.9583333333333
description: Total rental income.
alerts:
type: array
items:
type: object
properties:
message:
type: string
example: Choose the default income type on rental income tab to see the correct total income for JOHN SAMPLE.
description: Alert message.
severity:
type: string
example: HIGH.
description: Severity of the alert.
example: []
description: List of alerts related to rental income.
other_income:
type: object
properties:
is_income_calculated:
type: boolean
example: true
description: Indicates if the other income is calculated.
is_empty:
type: boolean
example: false
description: Indicates if the other income is empty.
total_income:
type: number
format: float
example: 2078.2166666666667
description: Total other income.
alerts:
type: array
items:
type: object
properties:
message:
type: string
example: Choose the default income type on other income tab to see the correct total income for JOHN SAMPLE.
description: Alert message.
severity:
type: string
example: HIGH.
description: Severity of the alert.
example: []
description: List of alerts related to other income.
total_income:
type: number
format: float
example: 11812.604166666668
description: Total income of the borrower.
status:
type: string
example: success
description: Status of the response.
message:
type: string
example: Success
description: A textual description that indicates details about this response's status.
total:
type: number
format: float
example: 18398.12416666667
description: Total income across all borrowers.
examples:
Success:
value:
book_uuid: c1c24601-19a8-41fb-b760-f76b538c929b
income_summary_data:
- borrower_uuid: a1d4c349-f630-4239-b268-ee22c7c23654
borrower_name: JOHN SAMPLE
wage_earner_income:
total_income: 1533.59
alerts:
- message: Choose the default income type on wage earner tab to see the correct total income for JOHN SAMPLE.
severity: HIGH
is_income_calculated: false
is_empty: false
self_employed_income:
is_income_calculated: true
is_empty: true
total_income: 0
alerts: []
rental_income:
is_income_calculated: true
is_empty: true
total_income: 0
alerts: []
other_income:
is_income_calculated: true
is_empty: true
total_income: 0
alerts: []
total_income: 1533.59
status: 200
message: Success
total: 1533.59
'400':
description: Client Errors
content:
application/json:
examples:
Invalid Auth:
value:
status: 400
code: 1200
response: null
message: Authentication failed
meta:
status: 400
msg: Authentication failed
code: 1200
Invalid guideline (400 BAD REQUEST):
value:
validation_error:
path_params:
- loc:
- book_uuid
msg: value is not a valid uuid
type: type_error.uuid
schema:
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 400
code:
type: integer
description: A numerical code that indicates the nature of an error.
example: 1401
response:
type: object
description: An object received from the server that potentially contains data.
message:
type: string
description: A textual description that indicates details about this response's status.
example: Book not found
meta:
type: object
description: An object received from the server that potentially contains data.
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
message:
type: string
example: Book not found
description: A textual description that indicates details about this response's status.
code:
type: integer
example: 1401
description: A numerical code that indicates the nature of an error.
'404':
description: Client Errors
content:
application/json:
examples:
Book not found:
value:
error: Book not found
schema:
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
message:
type: string
description: A textual description that indicates details about this response's status.
/v2/book/{book_uuid}/income-calculations:
get:
summary: Income calculations
operationId: income-calculations
tags:
- Income
description: "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.\n \n> \U0001F44D Tips\n> 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.\n"
parameters:
- name: book_uuid
in: path
required: true
description: The unique identifier of the <<glossary:Book>> from which the income calculations are retrieved.
schema:
type: string
format: uuid
example: 13e6d579-4699-43e2-a419-8a29bcb5f922
- name: guideline
in: query
required: false
description: 'The guideline to be used for retrieving the income calculations. Supported values include FANNIE_MAE, FREDDIE_MAC, FHA, VA, and USDA.
'
schema:
type: string
example: FANNIE_MAE
default: FANNIE_MAE
enum:
- FANNIE_MAE
- FREDDIE_MAC
- FHA
- VA
- USDA
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
title: Success
type: object
properties:
response:
type: object
description: Contains the detailed income calculations and related data.
properties:
book_uuid:
type: string
format: uuid
description: Unique identifier for the income calculation <<glossary:Book>>.
example: 13e6d579-4699-43e2-a419-8a29bcb5f922
incomes:
type: array
description: List of the borrower's income sources used for calculations.
items:
type: object
properties:
borrower_uuid:
type: string
format: uuid
description: Unique identifier of the borrower.
example: 8e52e9b6-6254-45a7-b008-1cebb825cfed
business_uuid:
type: string
format: uuid
description: Unique identifier for the business (if applicable).
example: 9857f0f3-991c-433c-ad77-f780b75a98fd
income_type:
type: string
description: Type of income. The available income types are -
example: SELF_EMPLOYED
enum:
- OTHER
- SELF_EMPLOYED
- WAGE_EARNER
- RENTAL
year:
type: string
description: Year of the income calculation.
example: '2022'
forms:
type: array
description: List of forms associated with the income calculation.
items:
type: object
properties:
form_type:
type: string
description: Type of the form.
example: A_1065_2022
form_uuid:
type: string
format: uuid
description: Unique identifier for the form.
example: b0d17733-42d9-448c-b7ce-f28c6f555c27
mixed_uploaded_doc_pk:
type: string
description: Primary key (PK) of the mixed uploaded document.
example: '14825462'
uploaded_doc_pk:
type: string
description: Primary key of the uploaded document.
example: '78169748'
page_doc_pks:
type: array
description: List of page document PKs.
items:
type: string
example: '548665097'
fields:
type: array
description: List of fields and their values for the income calculation.
items:
type: object
properties:
name:
type: string
description: Name of the field.
example: depletion
value:
type: string
description: Value of the field.
example: '0'
title:
type: string
description: Title or description of the field.
example: d. Depletion (Line 17)
page_doc_pk:
type: string
description: Primary key of the page document (if applicable).
example: '548665097'
calculated_fields:
type: array
description: List of calculated fields and their values.
items:
type: object
properties:
name:
type: string
description: Name of the calculated field.
example: subtotal
value:
type: string
description: Value of the calculated field.
example: '2000'
title:
type: string
description: Title or description of the calculated field.
example: Subtotal
currency:
type: string
description: Currency used for the income calculation.
example: USD
income_by_tax_returns:
type: string
description: IRS tax form used to report the income. The available forms are -
enum:
- IRS Form 1040 - Individual Income Tax Return
- IRS Form 1065 - Partnership Income
- IRS Form 1120 - Regular Corporation
- IRS Form 1120S - S Corporation Earnings
example: IRS Form 1065 - Partnership Income
xid:
type: string
description: A unique identifier for the borrower/employer pair.
example: XID-1
pay_type:
type: string
description: Pay type available for the wage earner income type. The available pay types are -
example: Misc Income
enum:
- Bonus Income
- Commission Income
- Hourly Income
- Military Income
- Misc Income
- Overtime Income
- Salary Income
- Shift Differential Income
other_income_collection:
type: string
description: Additional income sources not listed in standard income types. The available income types are -
enum:
- 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
example: Tip income
hourly_rate:
type: string
description: Hourly rate of the income source.
example: '23.0'
hours_worked_per_week:
type: string
description: Number of hours worked per week.
example: '16.0'
monthly_income:
type: string
description: Monthly income of the income source.
example: '0'
period_earnings:
type: string
description: Earnings for the specified period.
example: '0'
pay_frequency:
type: string
description: Frequency of pay (e.g., Weekly, Bi-Weekly, Monthly).
example: ''
is_active:
type: boolean
description: Indicates whether this income source is currently active.
example: true
is_selected:
type: boolean
description: Indicates whether this income source is selected.
example: true
borrowers:
type: array
description: List of borrowers associated with the income calculations.
items:
type: object
properties:
uuid:
type: string
format: uuid
description: Unique identifier for the borrower.
example: f27c4a63-9b1e-427e-8df6-6cc3fac16e58
name:
type: string
description: Name of the borrower.
example: JACK SMITH
employers:
type: array
description: List of employers associated with the income calculations.
items:
type: object
properties:
uuid:
type: string
format: uuid
description: Unique identifier for the employer.
example: e578b4b1-514e-4570-90fb-38951b6f7bd0
name:
type: string
description: Name of the employer.
example: FINANCE AND INSURANCE COMPANY
properties:
type: array
description: List of properties associated with the income calculations.
items:
type: object
properties:
uuid:
type: string
format: uuid
description: Unique identifier for the property.
example: 9b64690d-7448-41a2-b1a6-f2e9e01ed647
address:
type: string
description: Address of the property.
example: 123 MAIN STREET OCROLUS NY 54321
address_line1:
type: string
description: First line of the property's address.
example: 4257 W 158TH ST
city:
type: string
description: City where the property is located.
example: CLEVELAND
state:
type: string
description: State where the property is located.
example: OH
postal_code:
type: string
description: Postal code of the property's address.
example: '44135'
alerts:
type: array
description: List of alerts related to the income calculations.
items:
type: object
properties:
message:
type: string
description: Alert message.
example: Non-recurring income or losses detected on (Lines 5, 6 & 7) in 1065.
severity:
type: string
description: Severity level of the alert.
example: MEDIUM
income_type:
type: string
description: Type of income associated with the alert.
example: SELF_EMPLOYED
totals:
type: array
description: List of total calculated fields for each borrower's income type and business.
items:
type: object
properties:
borrower_uuid:
type: string
format: uuid
description: Unique identifier of the borrower.
example: a1d4c349-f630-4239-b268-ee22c7c23654
income_type:
type: string
description: Type of income (e.g., WAGE_EARNER, SELF_EMPLOYED, OTHER).
example
# --- truncated at 32 KB (168 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ocrolus/refs/heads/main/openapi/ocrolus-income-api-openapi.yml