# Get income summary

Retrieves a summary of an Individual's income based on the income related Items, including salary and other income related information. MeasureOne uses a set of heuristics to make a final determination. These heuristics are summarized in Reason Codes as detailed in the following table.

###  Reason Codes 
  |Code|Description|
  |--- |--- |
  |MIE_VF_DPC|Verification method: Direct payroll account connection|
  |MIE_VF_USP_BAC|Verification method: User-submitted paystub with bank account check|
  |MIE_VF_USP_NO_BAC|Verification method: User-submitted paystub without bank account check|
  |MIE_VF_USW2|Verification method: User-submitted W-2|
  |MIE_VF_US1099B| Verification method: User-submitted 1099-B|
  |MIE_VF_US1099OID| Verification method: User-submitted 1099-OID|
  |MIE_VF_US1099DIV| Verification method: User-submitted 1099-DIV|
  |MIE_VF_US1099INT| Verification method: User-submitted 1099-INT|
  |MIE_VF_US1099CONSOLIDATED| Verification method: User-submitted 1099-CONSOLIDATED|
  |MIE_VF_DPC_USP|Verification method: Direct payroll account connection and one or more User-submitted Paystub|
  |MIE_VF_DPC_USW2|Verification method: Direct payroll account connection and User-submitted W-2|
  |MIE_VF_USP_USW2|Verification method: User-submitted one or more Paystub and W-2|
  |MIE_VF_W2|Verification method: W-2 reported income is the wages, tips and other comp. (box 1) as reported on the W-2|
  |MIE_ERNG_1099INT|Interest income computed using data available on 1099-INT|
  |MIE_ERNG_1099DIV|Dividend income computed using data available on 1099-DIV|
  |MIE_ERNG_1099B|Investment income computed using data available on 1099-B|
  |MIE_ERNG_1099OID|Interest income computed using data available on 1099-OID|
  |MIE_ERNG_1099MISC|Rental income is Rents (box 1) as reported on 1099-MISC|
  |MIE_ERNG_1099MISC|Royalty income is Royalties (box 2) as reported on 1099-MISC|
  |MIE_ERNG_1099MISC|Other income is Other Income (box 3) as reported on 1099-MISC|
  |MIE_VF_US_EDR|Verification method: User-submitted THE WORK NUMBER Employment Data Report|
  |MIE_VF_UCB|Verification method: User-connected bank account|
  |MIE_DRVD_EIN|Employment Identification Number (EIN) derived from W-2|
  |MIE_NI_BEM|Net income on Paystub matches with a corresponding entry in the bank statement|
  |MIE_NI_NO_BEM|Net income on Paystub does not matches with a corresponding entry in the bank statement|
  |MIE_NID_BEM|Net income on Paystub matches with a corresponding entry in the bank statement (Deposit Split)|
  |MIE_INSUFFICIENT_DATA|Insufficient information to derive earnings|
  |MIE_INSUFFICIENT_DATA|Insufficient information to derive yearly earnings|
  |MIE_INSUFFICIENT_DATA|Insufficient information to derive an EIN|


Endpoint: POST /v3/services/get_income_summary
Version: 3.0
Security: Bearer

## Header parameters:

  - `version` (number)
    Version number of the MeasureOne API you wish to integrate.

  - `Authorization` (string)
    Authorization API Key

  - `Content-type` (string)
    Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

## Response 200 fields (application/json):

  - `individual` (object)

  - `individual.individual_id` (string)
    Unique ID of the Individual identified by MeasureOne

  - `individual.datasources` (array)

  - `datarequest_id` (string)
    Unique ID of the Data Request identified by MeasureOne

  - `service_context_id` (string)
    Unique ID of the service context identified by MeasureOne

  - `processing_status` (string)
    Processing status of the request.  - MeasureOne has finished processing of the request.  - We have received the request and system is acquiring the academic summary.
    Enum: "COMPLETED", "ACQUIRING"

  - `metadata` (object)
    metadata can be used for storing additional information in a structured format. metadata will be sent in webhooks and report response.

  - `income_summary` (array)

  - `income_summary.datasource` (object)
    Datasource details

  - `income_summary.datasource.id` (string)
    MeasureOne datasource identifier

  - `income_summary.datasource.type` (string)
    Type of datasource

  - `income_summary.datasource.name` (string)
    Name of datasource

  - `income_summary.datasource.provider_name` (string)
    Name of provider

  - `income_summary.as_of_date` (number)
    Timestamp (milliseconds) when this record was generated

  - `income_summary.remitter` (object)
    Remitter information

  - `income_summary.remitter.name` (string)
    Name of the Remitter

  - `income_summary.remitter.phone_number` (string)
    Phone number of the remitter

  - `income_summary.remitter.ein` (string)
    Employer identification number

  - `income_summary.remitter.address` (object)

  - `income_summary.remitter.address.addr1` (string)

  - `income_summary.remitter.address.addr2` (string)

  - `income_summary.remitter.address.city` (string)

  - `income_summary.remitter.address.state_name` (string)

  - `income_summary.remitter.address.zipcode` (string)

  - `income_summary.remitter.address.country` (object)

  - `income_summary.remitter.address.country.name` (string)

  - `income_summary.beneficiary` (object)
    Beneficiary information

  - `income_summary.beneficiary.first_name` (string)
    First name of the beneficiary

  - `income_summary.beneficiary.middle_name` (string)
    Middle name of the beneficiary

  - `income_summary.beneficiary.last_name` (string)
    Last Name of the beneficiary

  - `income_summary.beneficiary.email` (string)
    Email address of the beneficiary

  - `income_summary.beneficiary.prefix` (string)
    Name prefix

  - `income_summary.beneficiary.suffix` (string)
    Name suffix

  - `income_summary.beneficiary.gender` (string)
    Gender of the beneficiary

  - `income_summary.beneficiary.phone_number` (string)
    Phone number of the beneficiary

  - `income_summary.beneficiary.date_of_birth` (string)
    Date of Birth of the beneficiary in MM/DD/YYYY format.

  - `income_summary.beneficiary.ssn` (string)
    Social Security Number of the the beneficiary

  - `income_summary.earnings` (array)
    Earning of the beneficiary

  - `income_summary.earnings.type` (string)
    type of earning
    Enum: "SALARY", "WAGE", "INVESTMENT", "RENTAL", "COMMISSION", "INTEREST", "INVESTMENT", "ROYALTY", "GIFTS", "ALLOWANCE", "GOVERNMENT_PAYMENT", "DIVIDENDS", "RETIREMENT_PENSION", "TAX_REFUND", "UNEMPLOYMENT", "TRANSFER_IN", "OTHER_DEPOSITS", "OTHER"

  - `income_summary.earnings.basis` (string)
    Basis of earnings
    Enum: "HOURLY", "MONTHLY", "SEMI_MONTHLY", "WEEKLY", "ANNUAL", "BI_WEEKLY", "OTHER"

  - `income_summary.earnings.pay_date` (string)
    Payment date timestamp (milliseconds)

  - `income_summary.earnings.interval` (object)
    earning interval

  - `income_summary.earnings.interval.start_date` (number)
    earning start date timestamp (milliseconds)

  - `income_summary.earnings.interval.end_date` (number)
    earning end date timestamp (milliseconds)

  - `income_summary.earnings.amounts` (array)

  - `income_summary.earnings.amounts.currency` (string)
    Earning currency
    Enum: "USD", "OTHER"

  - `income_summary.earnings.amounts.type` (string)
    Type of amount
    Enum: "GROSS", "NET", "REGULAR", "OVERTIME", "BONUS", "COMMISSION", "OTHER", "W2_REPORTED_INCOME", "F1099_INT_REPORTED_INCOME", "F1099_DIV_REPORTED_INCOME", "F1099_B_REPORTED_INCOME", "F1099_OID_REPORTED_INCOME", "F1099_MISC_REPORTED_INCOME"

  - `income_summary.earnings.amounts.description` (string)
    Description of amount. Description would be populated when include_earnings_description is  for the request.

  - `income_summary.earnings.amounts.ytd_flag` (boolean)
    Indicates if the amount given is year to date

  - `income_summary.earnings.amounts.value` (number)
    Value of earning amount

  - `income_summary.yearly_earnings` (array)
    Yearly earnings of the beneficiary

  - `income_summary.yearly_earnings.year` (integer)
    year of earning

  - `income_summary.account_holders` (array)
    List of account holders associated with the connected bank account.

  - `income_summary.account_holders.name` (string)
    Name of the account holder

  - `income_summary.account_holders.email` (string)
    Email of the account holder

  - `income_summary.account_holders.phone_number` (string)
    Phone number of the account holder

  - `income_summary.account_holders.addresss` (object)
    Address of the account holder

  - `income_summary.reason_codes` (array)
    Array of reason codes used for determining the income summary. Helps developer understand how has the summary been derived.

  - `income_summary.reason_codes.code` (string)
    Reason code applicable

  - `income_summary.reason_codes.description` (string)
    Description providing details to understand how has the summary been derived.

  - `transaction_id` (string)
    Unique ID of this transaction.

## Response 400 fields (application/json):

  - `timestamp` (number)
    Timestamp in milliseconds

  - `error_code` (string)
    MeasureOne Error code

  - `error_message` (string)
    Details of the error

## Response 401 fields (application/json):

  - `timestamp` (number)
    Timestamp in milliseconds

  - `error_code` (string)
    MeasureOne Error code

  - `error_message` (string)
    Details of the error

## Response 404 fields (application/json):

  - `timestamp` (number)
    Timestamp in milliseconds

  - `error_code` (string)
    MeasureOne Error code

  - `error_message` (string)
    Details of the error

## Response 405 fields (application/json):

  - `timestamp` (number)
    Timestamp in milliseconds
    Example: 1655227025839

  - `error_code` (string)
    MeasureOne Error code
    Example: "METHOD_NOT_ALLOWED"

  - `error_message` (string)
    Details of the error
    Example: "Given Method not allowed"

## Response 409 fields (application/json):

  - `timestamp` (number)
    Timestamp in milliseconds
    Example: 1655227025839

  - `http_code` (number)
    Error status code
    Example: 409

  - `error_code` (string)
    MeasureOne Error code
    Example: "MULTIPLE_REPORT_INSTANCES"

  - `error_message` (string)
    Details of the error
    Example: "Multiple instances of the report INCOME_SUMMARY found in the Data Request. Please provide params/metadata in request"

## Response 422 fields (application/json):

  - `timestamp` (number)
    Timestamp in milliseconds

  - `error_code` (string)
    MeasureOne Error code

  - `error_message` (string)
    Details of the error

  - `reason_codes` (array)
    List of reason codes. Helps developer understand what error occurred during processing an item.

  - `reason_codes.code` (string)
    Reason code applicable
 |Reason Code|Description|
 |--- |--- |
 |UNSUPPORTED_FORMAT| The report could not be generated as the following items are of unsupported format.
 |UNPROCESSABLE_DOCUMENT_QUALITY| The report could not be generated as the following items are unprocessable.
 |PARTIAL_DOCUMENT| The report could not be generated as the following items are partial.
 |NO_ITEMS| The report could not be generated as there are no items for this Individual.

  - `reason_codes.description` (string)
    Description providing details to understand what error occurred during processing an item.

  - `reason_codes.context` (object)
    Context to understand where the reason code is applicable

  - `reason_codes.context.items` (array)
    List of Items where the reason code is applicable

## Response 500 fields (application/json):

  - `timestamp` (number)
    Timestamp in milliseconds

  - `error_code` (string)
    MeasureOne Error code

  - `error_message` (string)
    Details of the error