Generate Affordability Insights
Get Started
Before requesting affordability insights, create a case and share bank transaction data either by uploading bank statements and / or by creating an open banking connection.
Create a Case
Create a case using the create case endpoint. A case can optionally contain companies and/or people. You can share bank transaction data and request Affordability Insights at the case, person or company level.
- For unique insights for individual applicants within a case, add each person as a
personentity, upload relevant documents, create open banking connections, and request insights perperson. - For joint applications, add all necessary documents or connections to the
caseand request insights for the entirecase.
If joint bank accounts or statements are being used, upload transaction data and request Affordability Insights at the
caselevel.
Upload Bank Statements
Upload bank statements using the upload document endpoint. Ensure the entity_id and entity_type are specified in the request. For accurate insights, upload at least three months of statements.
Learn about the criteria bank statements must meet and explore the list of supported banks and institutions here.
When a bank statement has been uploaded and we have attempted to extract the data from it we will try to send a BankStatementProcessing.Completed webhook if one has been configured in our API. For full details, please see the Bank Statement Processing Completed Webhook section.
Create an Open Banking Connection
As an alternative to uploading bank statements, connect a bank account for a UK bank using open banking by utilising the relevant open banking connection endpoint.
You can find more information on the types of connected accounts that can be used to generate an affordability insights here.
When an open banking connection has been completed we will try to send a OpenBankingProcessing.Completed webhook if one has been configured in our API. For full details, please see the Open Banking Processing Completed Webhook section.
Review Data Sources
If you're not using webhooks or if you want to view all the data sources which have been provided for a given entity, you can also verify the processing status for all documents and open banking connections using our data sources endpoint.
Learn more about data sources here.
Before requesting Affordability Insights, ensure the status is Complete for all data sources you wish to use. Data Sources with a Provided, Failed, or Pending statuses cannot be used to generate affordability insights.
Generate Affordability Insight Request
Once you've created a case and successfully uploaded the relevant documents or created the relevant open banking connections, you can request affordability insights.
Use the POST Affordability Insights endpoint to initiate the affordability insights request for the specific entity.
{
"request_id": "a5f84a41-01cf-4d21-901d-124c5a7c743a",
"status": "Pending",
"entity_id": "7885857d-fa2b-43ab-8b15-67e5fea8e896",
"entity_type": "case",
"datetime_requested": "2023-11-24T12:38:45.711Z",
"message": "Affordability insights pending"
}
Record the request_id from the response as it will be required to check the status.
Check the Status of the Request
If you have configured any webhooks that reference the AffordabilityInsights.Completed event you will receive a request of this event type as soon as the affordability insights process has completed. Check out our webhooks guide for more information on how to set up and configure webhooks.
Alternatively, you can monitor the status by polling the GET Affordability Insights endpoint. Specify the request_id for the relevant entity in the request. Wait for a Complete status to be achieved before retrieving the Affordability Insights.
{
"request_id": "a5f84a41-01cf-4d21-901d-124c5a7c743a",
"status": "Pending",
"entity_id": "7885857d-fa2b-43ab-8b15-67e5fea8e896",
"entity_type": "case",
"datetime_requested": "2023-11-24T12:38:45.711Z",
"message": "Affordability insights pending"
Retrieve Affordability Insights
Once you've requested affordability insights and the status of your request is complete, you can retrieve the results. There are two parts to this process:
Retrieve the Overview
This overview provides the cashflow summary and indicators. The cashflow summary shows typical monthly income, essential expenditure, and non-essential expenditure, broken down by category. Indicators highlight transactions that meet specific criteria such as transactions pertaining to gambling, childcare and insurance.
Use the GET Affordability Insights endpoint and ensure the relevant request_id is specified in the URL.
{
"request_id": "a5f84a41-01cf-4d21-901d-124c5a7c743a",
"status": "Complete",
"entity_id": "7885857d-fa2b-43ab-8b15-67e5fea8e896",
"entity_type": "case",
"datetime_requested": "2023-11-29T12:21:52.933Z",
"datetime_completed": "2023-11-29T12:22:07.747Z",
"data": {
"cashflow": [
{
"group": "Income",
"value": 5249.19,
"categories": [
{
"name": "Regular wage and salary",
"value": 5109.45
},
{
"name": "Benefits",
"value": 139.74
}
]
},
{
"group": "Essential expenditure",
"value": -3360.77,
"categories": [
{
"name": "Utilities",
"value": -1279.63
},
{
"name": "Groceries and shopping",
"value": -2081.14
}
]
}
],
"indicators": [
{
"name": "Benefits",
"present": true
}
]
}
}
For a full list of potential groups, categories, and indicators click here.
Retrieve the Detailed Transaction View
The detailed transaction view provides a comprehensive breakdown of categorised transactions, providing granular view of monthly, aggregate and average spend by merchant, grouped by category.
Use the GET Affordability Insights endpoint and ensure the relevant request_id is specified in the URL.
{
"request_id": "a5f84a41-01cf-4d21-901d-124c5a7c743a",
"status": "Complete",
"entity_id": "7885857d-fa2b-43ab-8b15-67e5fea8e896",
"entity_type": "case",
"datetime_requested": "2023-11-29T12:21:52.933Z",
"datetime_completed": "2023-11-29T12:22:07.747Z",
"data": [
{
"group": "Essential expenditure",
"category": "Utilities",
"short_description": "EE Limited",
"number_of_transactions": 6,
"total_value": -271.44,
"average_value": -45.24,
"minimum_value": -50.34,
"maximum_value": -40.14,
"monthly_data": [
{
"year": 2023,
"month": 10,
"total_value": -90.48
},
{
"year": 2023,
"month": 9,
"total_value": -90.48
},
{
"year": 2023,
"month": 8,
"total_value": -40.14
},
{
"year": 2023,
"month": 11,
"total_value": -50.34
}
]
},
{
"group": "Essential expenditure",
"category": "Groceries and shopping",
"short_description": "Tesco Store Hook",
"number_of_transactions": 40,
"total_value": -1209.16,
"average_value": -30.23,
"minimum_value": -56.24,
"maximum_value": -3.66,
"monthly_data": [
{
"year": 2023,
"month": 10,
"total_value": -419.2
},
{
"year": 2023,
"month": 11,
"total_value": -97.38
},
{
"year": 2023,
"month": 9,
"total_value": -451.62
},
{
"year": 2023,
"month": 8,
"total_value": -240.96
}
]
}
]
}
Updated 5 days ago