Inscribe provides a quick and easy method to verify a customer’s income. This feature, called Income Verification, allows users to define an expected income for a given customer. After the submission of documents and/or open banking data, Inscribe provides an easy-to-use boolean with the verification result; true if the customer exceeds the expected income amount, or false otherwise.

This guide provides a concise overview of the steps needed to verify a customer's income.

📘

Prerequisite(s)

• Retrieve your API key as detailed here .

Conduct Income Verification Flow

• Create Customer with Income Verification arguments.
• Associate financial data with the Customer. Financial data in this scenario can be in the form of bank statement documents, payslips, or Open Banking data. Both forms of financial data can be submitted simultaneously and the transactions will be returned with the data source identified.
• Verify Customer hasn’t uploaded fraudulent documents.
• Retrieve the Income Verification result.

Step by Step

 1. Create Customer with Income Verification arguments

To begin, we must create a customer. Additional information on creating a customer can be viewed here. In order to create an Income Verification request, the following arguments must be included:

• income refers to the type of income that is to be verified for the customer. This can be either personal_income or revenue.
• input is the expected income amount that is to be verified (in cents).
• lower_income_tolerance is the tolerance with which found incomes below the input amount are verified. For example, if this value is set to 0.1, an income will be verified if it is at least 90% (1-lower_income_tolerance) of the input amount.
• under_reported_tolerance is the tolerance with which found incomes above the input amount are set to under_reported. For example, if this value is set to 0.1, an income will be set to under_reported if it is at least 110% (1+under_reported_tolerance) of the input amount.
• frequency refers to the frequency of the income to check. Currently, the only income that can be checked is annual income.

import requests  
URL = "<https://api.inscribe.ai/api/v2>"  
API_KEY = "Inscribe ..."

headers = {  
    "Authorization": API_KEY,  
    "accept": "application/json",  
    "content-type": "application/json"  
}

payload = {  
    "verify_entity": {"income": {"personal_income": {  
                "input": 20000_00,  
                "lower_income_tolerance": 0.1,  
                "under_reported_tolerance": 0.5,  
   "frequency": "annual"  
            }}},  
    "name": "John Smith"  
}

response = requests.post(f"{URL}/customers", json=payload, headers=headers)  
customer = response.json()

2. Associate Financial Data with the Customer

Once your customer has been created, we must associate transactional data with the customer. This data can be in the form of bank statements or open banking data. Both forms can also be associated with the one customer.

To Submit a Document:

customer_id = customer["id"]  
with open("DOCUMENT_FILE_PATH", "rb+") as document:  
    filename = os.path.basename(document.name)  
    files = {"file": (filename, document, "application/octet-stream")}  
    response = requests.post(  
        f"{URL}/customers/{customer_id}/documents",  
        files=files,  
        headers=headers  
    )

To Submit Open Banking Data:

customer_id = customer["id"]  
with open("PLAID_ASSET_FILE_PATH", "r") as asset_report:  
    data = asset_report.read()  
    response = requests.post(  
        f"{URL}/customers/{customer_id}/plaid_assets",  
        headers=headers,  
        data=data  
    )

🚧

Check Fraud Statuses

Before ingesting any insights, it is highly recommended to inspect the returned document Trust Scores. This value is a measure of how much Inscribe trusts a document.

3. Retrieve Income Verification Status

After the customer data has been uploaded and processed, the Income Verification status is ready to be queried. To do this, we use a GET request on the customer.

url = f"<https://api.inscribe.ai/api/v2/customers/{customer_id}>"  
response = requests.request("GET", url, headers=headers)  
customer_response = response.json()  
print(customer_response)

The response will contain the parameters set in the request, as well as a number of other fields. These fields can be interpreted as follows:

• verified is the status of the verification request. This will be set to true if the found income was greater than or equal to the input value (adjusted by any given lower_income_tolerance). It will be set to false if the input value did not meet that threshold. If no relevant documents have been provided, this value is set to null.
• matched is the found income amount (in cents).
• amount_type is the type of the found income e.g. gross or net.
• under_reported is set to true if the found income exceeded the input amount. It is set to false if the found income did not. It is set to null if no relevant documents were provided or if the income was not verified.

📘

Income Insights

For more in-depth insights about the customer’s income, use the income_insights endpoint.