Get gross monthly income input broken down by base, commission, bonus, overtime and total for one or more persons' for use in an income calculation worksheet by using their paystubs and W-2s. This endpoint also returns the "data inputs" extracted to calculate this income.

🚧

This endpoint is in beta!

This endpoint is currently in beta, and is therefore subject to change. We would greatly appreciate it if you reported any feedback (including bugs) to customer service.

General rules followed

  • We are able to differentiate between multiple borrowers within a single book when calculating income
  • If paystubs for a borrower’s current place of employment have overlapping time periods, we aggregate incomes of the same pay type (eg. base, overtime, bonus, commission)
  • Borrowers need two years worth of paystub data for their overtime, bonus and/or commission pay to get counted
  • If we determine an income pay type to be invalid (for example, if rule above applies) we will still return the data inputs and intermediary calculations but the chosen income will be 0 and the "calculation_used" field will return "do_not_use_income"
  • If any paystubs or W-2s is missing an employer name, we will return the calculated inputs and results in an "UNKNOWN" employer object
  • Tax years for provided documents must be consecutive and must fit within a three year period
  • Income trends:
    • If the income increasing over time, we use its average over the years
    • If the income declined and is now stable, we use the most recent income
    • If the income still declining, we still calculate the income but additional analysis may be required by the underwriter

Traditionally Employed Income Fields

Top level fields

Attribute name

Attribute data type

Attribute description

book_uuid

UUID

A universally unique identifier assigned to the Book passed in to this endpoint.

income_calculations

array of objects

Array of objects, where each object corresponds to a given person and their respective income.

Income calculations object

Attribute name

Attribute data type

Attribute description

person.name

string

The person who's income is calculated in this object.

person.matched_names

array of strings

The names found on paystubs and W2s that we associated to this person.

calculated_at

timestamp

Time at which the calculations were run.

currency

currency

Three-letter ISO currency code in which we estimated the person's income.

income_by_current_employers

array of objects

Array of objects, where each object corresponds to income calculations for a person's current place of employment.

Income by current employers object

Attribute name

Attribute data type

Attribute description

employer.name

string

The person's current place of employment for which income is calculated in this object.

employed.matched_names

array of strings

The names found on paystubs and W2s that we associated to this employer.

estimated_gross_income

object containing objects

Object containing the final income calculation results for each pay type.

income_by_pay_type

object containing objects

Object containing the data inputs, intermediary calculations and final results for each pay type.

documents_used

object containing objects

Object containing the documents used for this person / employer combination.

documents_not_used

object containing objects

Object containing the documents not used for this person / employer combination.

Estimated gross income object

Attribute name

Attribute data type

Attribute description

monthly_base.value

string

The person's average base pay for a month.

monthly_base.calculation_used

string

The income or average used to get the value above.

monthly_overtime.value

string

The person's average overtime pay for a month.

monthly_overtime.calculation_used

string

The income or average used to get the value above.

monthly_bonus.value

string

The person's average bonus pay for a month.

monthly_bonus.calculation_used

string

The income or average used to get the value above.

monthly_commission.value

string

The person's average commission pay for a month.

monthly_commission.calculation_used

string

The income or average used to get the value above.

monthly_other.value

string

The person's average other pay for a month.

monthly_other.calculation_used

string

The income or average used to get the value above.

monthly_total.value

string

The person's average total pay for a month.

monthly_total.calculation_used

string

Sum of all of the above pay types' values.

Income by pay type object

Attribute name

Attribute data type

Attribute description

hourly_pay_data

object

Object containing the data inputs, intermediary calculations and final results the person's hourly pay.

salary_pay_data

object

Object containing the data inputs, intermediary calculations and final results the person's salary pay.

overtime_pay_data

object

Object containing the data inputs, intermediary calculations and final results the person's overtime pay.

bonus_pay_data

object

Object containing the data inputs, intermediary calculations and final results the person's bonus pay.

commission_pay_data

object

Object containing the data inputs, intermediary calculations and final results the person's commission pay.

other_pay_data

object

Object containing the data inputs, intermediary calculations and final results the person's other pay.

Pay type data object (hourly, salary, overtime, bonus, commission)

Attribute name

Attribute data type

Attribute description

inputs

object

Object containing all the inputs used in the calculations.

inputs.paystub_data

array of objects

Array of objects with paystub data (default is [] when no paystubs have this pay type).

inputs.paystub_data[].tax_year

integer

Tax year for this object’s paystub.

inputs.paystub_data[].hourly_rate

string

Specific to hourly pay type: weighted average of the number of dollars earned per hour for the given tax year.

inputs.paystub_data[].hours_worked_per_week

string

Specific to hourly pay type: average number of hours worked per week for the given tax year.

inputs.paystub_data[].monthly_salary

string

Specific to salary pay type: monthly income calculated using the paystub earnings and pay frequency.

inputs.paystub_data[].ytd_earnings

string

Year to date, pay type specific, paystub earnings for the the given tax year.

inputs.paystub_data[].ytd_months_elapsed

string

Year to date months elapsed in the paystub for the given tax year.

inputs.paystub_data[].ytd_monthly_income

string

Monthly income calculated using the YTD earnings and months elapsed.

inputs.w2_data

array of objects

The person's W-2 data for a given tax year.

inputs.w2_data[].earnings

string

The person's W-2 earnings for a given tax year.

inputs.w2_data[].tax_year

integer

The tax year for the W-2 data.

inputs.w2_data[].monthly_income

string

The person's W-2 earnings for the given tax year divided by 12.

calculations

object

Intermediary calculations used to get to the chosen income for this pay type.

calculations.monthly_income_hourly_data

string

Specific to hourly pay type: monthly income calculated using the hourly rate and hours worked / week.

calculations.ytd_avg

string

Monthly income calculated using the YTD earnings and YTD months elapsed.

calculations.ytd_1_year_avg

string

Monthly income calculated using a weighted average of YTD and past year earnings with YTD months elapsed.

calculations.ytd_2_year_avg

string

Monthly income calculated using a weighted average of YTD and past two year earnings with YTD months elapsed.

calculations.chosen_income

string

The final income returned for the relevant pay type in the estimated gross income object.

Documents used object

Attribute name

Attribute data type

Attribute description

paystub_docs

array of objects

Each object in this array is a different paystub.

paystub_docs.name

string

File name (with its extension) containing the paystub.

paystub_docs.pages

array

The pages at which this paystub appears in the file.

paystub_docs.date

string

The end date of the paystub pay period.

w2_docs

array of objects

Each object in this array is a different W2.

w2_docs.name

string

File name (with its extension) containing the W2.

w2_docs.pages

array

The pages at which this W2 appears in the file.

w2_docs.year

integer

The W2's tax year.

Documents not used object

Attribute name

Attribute name

Attribute description

paystub_docs

array of objects

Each object in this array is a different paystub.

paystub_docs.name

string

File name (with its extension) containing the paystub.

paystub_docs.pages

array

The pages at which this paystub appears in the file.

paystub_docs.date

string

The end date of the paystub pay period.

paystub_docs.reason

string

The reason for which this paystub was not used.

w2_docs

array of objects

Each object in this array is a different W2.

w2_docs.name

string

File name (with its extension) containing the W2.

w2_docs.pages

array

The pages at which this W2 appears in the file.

w2_docs.year

integer

The W2's tax year.

w2_docs.reason

string

The reason for which this W2 was not used.

Sample PDF

The below is a sample Cacluate PDF.

Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!