Income Clear

Overview

Whether you're a tenant lease company or a government benefits administrator or a lender, there is a time and cost associated with performing income verification. For lenders, the data shows that capture rates drop by up to 50% when credit approval requires an income verification. The more friction lenders add to the originations process, the lower the odds of the deal closing.

Income Clear is a non-FCRA compliant, non-documentary validation product that allows you to quickly assess how an applicant's stated income compares to that of similarly employed workers based on occupation, employer and geographic area according to the Bureau of Labor Statistics' Occupational Employment and Wage Statistics (BLS OEWS). Income Clear allows you to more confidently make the decision as to whether you should skip the income verification or not.

More information regarding the BLS OEWS is available at here.

Process Flow

Please reference the full sequence_diagram.

URL Endpoint

The table below shows the URL to be used for the requests mentioned in this guide.

Environment	Base URL
Staging:	https://api.staging.informediq-infra.com/v1/skip-the-stip
Production:	https://api.informediq.com/v1/skip-the-stip

Full Example Request

You will need to make a POST request to the Informed Income Clear endpoint with a payload similar to the code block below. The following section provides details on the key nodes of the request payload.

{
  "occupation": "Elementary school teacher",
  "employer_name": "Acme Public School",
  "zip_code": "48306",
  "stated_income": 70000,
  "partner_application_reference_id": "test_application_1234",
  "sources": ["bls-oews"]
}

Request Components

Element	Value	Description
occupation	string	Required Applicant’s occupation Example: Software engineer
employer_name	string	Optional Applicant’s employer name; this will be used to enhance mapping of occupation
zip_code	string	Required Applicant’s zip code, it is formatted as a string due to the fact that some zip codes start with a zero
stated_income	numeric	Optional Yearly income amount as reported by the applicant (in USD)
partner_application_reference_id	string	Optional The expectation is that this value would be unique to the api caller. It does not have to be unique in every request. If you wanted to send multiple Income Clear requests for the same application, you should use the same value each time. This value can also be useful for debugging potential duplicate calls or other situations.
sources	list	Required List of data sources you want to accesss for this application. The data source needs to be configured for your financial institution before adding it to the request Example: ["bls-oews"]

Synchronous Response

2xx responses

A set of test seeds will be provided once you start development and have your credentials. Example output payloads are shown for each of the five possible status values described in the table below.

{
  "bls-oews": {
    "mean_income": 69580.0,
    "median_income": 64430.0,
    "10pct_income": 39500.0,
    "25pct_income": 50080.0,
    "75pct_income": 80660.0,
    "90pct_income": 100920.0,
    "standard_occupational_classification": "Elementary School Teachers, Except Special Education",
    "data_source_version": 2021,
    "area_code": "19820",
    "human_readable_area": "Detroit-Warren-Dearborn, MI",
    "status": "MATCH_FOUND"
  }
}

{
  "bls-oews": {
    "mean_income": null,
    "median_income": null,
    "10pct_income": null,
    "25pct_income": null,
    "75pct_income": null,
    "90pct_income": null,
    "standard_occupational_classification": null,
    "data_source_version": 2021,
    "area_code": "41940",
    "human_readable_area": "San Jose-Sunnyvale-Santa Clara, CA",
    "status": "NO_MATCH_FOUND"
  }
}

{
  "bls-oews": {
    "mean_income": null,
    "median_income": null,
    "10pct_income": null,
    "25pct_income": null,
    "75pct_income": null,
    "90pct_income": null,
    "standard_occupational_classification": "Fishing and Hunting Workers",
    "data_source_version": 2021,
    "area_code": "5300006",
    "human_readable_area": "Western Washington nonmetropolitan area",
    "status": "INSUFFICIENT_DATA"
  }
}

{
  "bls-oews": {
    "mean_income": null,
    "median_income": null,
    "10pct_income": null,
    "25pct_income": null,
    "75pct_income": null,
    "90pct_income": null,
    "standard_occupational_classification": null,
    "data_source_version": 2021,
    "area_code": "41940",
    "human_readable_area": "San Jose-Sunnyvale-Santa Clara, CA",
    "status": "UNSUPPORTED_OCCUPATION"
  }
}

{
  "bls-oews": {
    "mean_income": null,
    "median_income": null,
    "10pct_income": null,
    "25pct_income": null,
    "75pct_income": null,
    "90pct_income": null,
    "standard_occupational_classification": null,
    "data_source_version": null,
    "area_code": null,
    "human_readable_area": null,
    "status": "INVALID_INPUT_FORMAT"
  }
}

Non-2xx responses

Status	Error Message
500	Something went wrong :( Indicates some internal failure occurred. You should contact your support representative.

Response Components

A successful API request will return a synchronous response with the Income Clear results like the examples shown above. The highest level of the response will have the keys corresponding to the sources of data specified in the request. As of now, Informed only supports the "bls-oews" data source. Every data source could have different elements based on the specifications of the data source.

BLS - OEWS

For the U.S. Bureau of Labor Statistics (OEWS) data source, the key is bls-oews and the elements contained within are detailed below.

Element	Value	Description
mean_income	numeric	Mean yearly income based on the occupation and the area of the applicant as reported in BLS data Or it can be null if there is insufficient data, an unsupported occupation, invalid input or no match found.
median_income	numeric	Median yearly income based on the occupation and the area of the applicant as reported in BLS data Or it can be null if there is insufficient data, an unsupported occupation, invalid input or no match found.
10pct_income	numeric	Tenth percentile yearly income based on the occupation and the area of the applicant as reported in BLS data Or it can be null if there is insufficient data, an unsupported occupation, invalid input or no match found.
25pct_income	numeric	Twenty-fifth percentile yearly income based on the occupation and the area of the applicant as reported in BLS data Or it can be null if there is insufficient data, an unsupported occupation, invalid input or no match found.
75pct_income	numeric	Seventy-fifth percentile yearly income based on the occupation and the area of the applicant as reported in BLS data Or it can be null if there is insufficient data, an unsupported occupation, invalid input or no match found.
90pct_income	numeric	Ninetieth percentile yearly income based on the occupation and the area of the applicant as reported in BLS data Or it can be null if there is insufficient data, an unsupported occupation, invalid input or no match found.
standard_occupational_classification	string	Standardized Occupation of the applicant as per BLS definition. The list of occupations can be found here. Or it can be null if there is an unsupported occupation, invalid input or no match found.
data_source_version	numeric	Informed will use the latest version of the BLS data based on the date of the request, for example: 2022 Or it can be null if there is invalid input.
area_code	string	The area code is a string containing 2-7 numeric digits that represents a geographic area per the BLS data. It is returned as a string because there can be leading zeros. More information can be found below. Or it can be null if there is invalid input.
human_readable_area	string	A string containing a human readable description of the geographic area specified by the area_code above. More information can be found below. Or it can be null if there is invalid input.
status	string	Status of the BLS lookup. The five possible values are explained in the table below.

Supporting information

Status values

There are five possible values for the status property of the response. The status value helps explain the outcome of the BLS lookup for a given applicant's information.

Status	Description
MATCH_FOUND	A match was found in the BLS data and thus the income statistics will be supplied.
NO_MATCH_FOUND	Occupation/Area is incorrect or incomplete and doesn’t have any match in BLS data. Therefore, the income statistics will be empty.
INSUFFICIENT_DATA	The BLS data doesn't have enough entries for meaningful statistics. Therefore, the income statistics will be empty.
UNSUPPORTED_OCCUPATION	There are some occupations that will never have a match, regardless of area, and we want to make sure to distinguish these from the normal situation of no match for a given occupation/area. Examples include "Retired", "Pension", "Social Security", "Self-Employed". No income statistics will be supplied for this status.
INVALID_INPUT_FORMAT	This status will result if the request payload was not properly formed. Examples might include leaving out a required field or submitting a numeric value where a string was expected. No income statistics will be supplied for this status.

Area codes and statistical areas

Metropolitan Statistical Areas (MSA) are represented by a unique five-digit code per MSA. Example: 41940 (San Jose-Sunnyvale-Santa Clara, CA)

Non-metropolitan areas are represented by a seven-digit code made up of the state code followed by a numerical ID for the specified non-metropolitan area in that state. Example: 5300006 (Western Washington nonmetropolitan area -- in this case, the sixth such non-metropolitan area in Washington state, which has state code 53)

State codes (sometimes referred to as FIPS codes) are two-digit codes between 1-98 (left padded with a zero as necessary to maintain two digits for codes with a numerical value less than 10). Example: 06 (CA)

If none of the previous area codes are able to be determined, we will use the generic code for the USA, which is 99.

The detailed listing of all FIPS and MSA codes can be found here.