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 person entity, upload relevant documents, create open banking connections, and request insights per person.
For joint applications, add all necessary documents or connections to the case and request insights for the entire case.

ℹ️
If joint bank accounts or statements are being used, upload transaction data and request Affordability Insights at the case level.

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.

Bank statements must meet the following criteria:

Statements must be from a supported UK bank. You can find a list of supported banks here.
Statements must be in PDF format, base64 encoded.
Statements must be downloaded directly from the official bank website or mobile application. Photos or scanned copies are not supported.
Statements must be unaltered and unencrypted.
Statements must be for a joint or individual bank account or credit card. Mortgage statements and loan statements are not supported.

⚠️
Safari, Firefox and Edge browsers may alter the documents if viewed in the browser and then saved, either directly or via a “print to pdf” function.

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.

The possible statuses are:

Provided: The document has been successfully uploaded into the system but has not been processed.
Pending: The data source is being processed.
- If the data source is a document, it is in the process of being classified or being extracted.
- If the data source is an open banking connection, the user has not yet completed the authorisation process.
Complete: The data source has been successfully processed.
Failed: The data source could not be processed for some reason. If a failed status is returned, a message will also be returned which includes more information on what the data source could not be processed.
Excluded: The data source has been deleted or is not supported.

Before requesting Affordability Insights, ensure the status is Complete for all data sources you wish to use. Data Sources with a Provided Failed, Pending, or Excluded 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
        }
      ]
    }
  ]
}