Affordability
Returns identified recurring sources of income, such as salary payments, benefits, pensions etc.
Potential Use Cases:
- Detect recurring income
- Distinguish salary structure: monthly, fortnightly, ad-hoc/contractor
The Insights webhook is HTTPS post request and a typical example of the request body is as follows:
{
"type": "INSIGHTS",
"data": {
"metadata": {
"merchantId": "684af205b26c48042487c93c",
"customerId": "eixyc0oxx9o0",
"reference": "eixyc0oxx9o0",
"citizenTransactionId": "54f97545-a987-cfa9-b2a8-f66b97",
"merchantTradingName": "Test Merchant"
},
"insightGroup": {
"id": "68d6593704a1aa70943d2bb1",
"name": "Affordability insights",
"insights": [
"AFFORDABILITY"
],
"period": [
"MONTHLY"
],
"fromDate": "2025-06-28T09:32:33.440188Z",
"toDate": "2025-09-26T09:32:33.440206Z"
},
"insights": {
"AFFORDABILITY": {
"insight": "AFFORDABILITY",
"fromDate": "2025-04-01T00:00:00Z",
"toDate": "2025-07-31T23:59:59Z",
"assessableIncome": {
"qualifyingIncomeTypes": [
"Salary",
"State Pension",
"Gig",
"Other income",
"Gambling"
],
"statistics": [
{
"currency": "GBP",
"MONTHLY": {
"average": 125,
"standardDeviation": 129.9
}
},
{
"currency": "GBP",
"MONTHLY": {
"average": 1852.5,
"standardDeviation": 1886.6
}
}
],
"period": {
"MONTHLY": [
{
"fromDate": "2025-04-01T00:00:00Z",
"toDate": "2025-04-30T23:59:59Z",
"byCurrency": [
{
"currency": "GBP",
"amount": 0
},
{
"currency": "EUR",
"amount": 0
}
]
},
{
"fromDate": "2025-05-01T00:00:00Z",
"toDate": "2025-05-31T23:59:59Z",
"byCurrency": [
{
"currency": "EUR",
"amount": 200.0
},
{
"currency": "GBP",
"amount": 4210.0
}
]
},
{
"fromDate": "2025-06-01T00:00:00Z",
"toDate": "2025-06-30T23:59:59Z",
"byCurrency": [
{
"currency": "GBP",
"amount": 3200.0
},
{
"currency": "EUR",
"amount": 300.0
}
]
},
{
"fromDate": "2025-07-01T00:00:00Z",
"toDate": "2025-07-31T23:59:59Z",
"byCurrency": [
{
"currency": "GBP",
"amount": 0
},
{
"currency": "EUR",
"amount": 0
}
]
}
]
}
},
"accounts": [
{
"accountId": "6414EEAB-8BD6-4B18-8AEE-72B10A407930",
"bank": "HALIFAX",
"currency": "GBP",
"consents": [
{
"lastUpdateAt": "2025-07-22T00:00:00Z",
"status": "ACTIVE",
"createdAt": "2025-06-22T00:00:00Z",
"expiresAt": "2025-09-22T00:00:00Z"
}
],
"income": {
"statistics": {
"totalAmount": 5710.0,
"MONTHLY": {
"average": 1427.5,
"standardDeviation": 1455.94
}
},
"period": {
"MONTHLY": [
{
"fromDate": "2025-04-01T00:00:00Z",
"toDate": "2025-04-30T23:59:59Z",
"totalAmount": 0,
"transactions": []
},
{
"fromDate": "2025-05-01T00:00:00Z",
"toDate": "2025-05-31T23:59:59Z",
"totalAmount": 3260.0,
"transactions": [
{
"incomeType": "Salary",
"totalAmount": 1000.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-05-29T10:00:00Z"
},
{
"incomeType": "Salary",
"totalAmount": 1000.0,
"frequency": "irregular",
"quantity": 1,
"lastPaymentDate": "2025-05-11T10:00:00Z"
},
{
"incomeType": "Gig",
"totalAmount": 500.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-05-05T10:00:00Z"
},
{
"incomeType": "State Pension",
"totalAmount": 760.0,
"frequency": "weekly",
"quantity": 4,
"lastPaymentDate": "2025-05-26T10:00:00Z"
},
{
"incomeType": "Benefits",
"totalAmount": 100.0,
"frequency": "irregular",
"quantity": 1,
"lastPaymentDate": "2025-05-20T10:00:00Z"
}
]
},
{
"fromDate": "2025-06-01T00:00:00Z",
"toDate": "2025-06-30T23:59:59Z",
"totalAmount": 2450.0,
"transactions": [
{
"incomeType": "Salary",
"totalAmount": 1000.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-06-29T10:00:00Z"
},
{
"incomeType": "Private Pension",
"totalAmount": 500.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-06-05T10:00:00Z"
},
{
"incomeType": "Gig",
"totalAmount": 950.0,
"frequency": "weekly",
"quantity": 5,
"lastPaymentDate": "2025-06-30T10:00:00Z"
}
]
},
{
"fromDate": "2025-07-01T00:00:00Z",
"toDate": "2025-07-31T23:59:59Z",
"totalAmount": 0,
"transactions": []
}
]
}
}
},
{
"accountId": "09963B8C-CD90-446A-8FA7-22B78855A9F7",
"bank": "HALIFAX",
"currency": "EUR",
"consents": [
{
"lastUpdateAt": "2025-07-22T00:00:00Z",
"status": "ACTIVE",
"createdAt": "2025-06-22T00:00:00Z",
"expiresAt": "2025-09-22T00:00:00Z"
}
],
"income": {
"statistics": {
"totalAmount": 500.0,
"MONTHLY": {
"average": 125,
"standardDeviation": 129.9
}
},
"period": {
"MONTHLY": [
{
"fromDate": "2025-04-01T00:00:00Z",
"toDate": "2025-04-30T23:59:59Z",
"totalAmount": 0,
"transactions": []
},
{
"fromDate": "2025-05-01T00:00:00Z",
"toDate": "2025-05-31T23:59:59Z",
"totalAmount": 200.0,
"transactions": [
{
"incomeType": "Other income",
"totalAmount": 200.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-05-26T10:00:00Z"
}
]
},
{
"fromDate": "2025-06-01T00:00:00Z",
"toDate": "2025-06-30T23:59:59Z",
"totalAmount": 300.0,
"transactions": [
{
"incomeType": "Other income",
"totalAmount": 300.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-06-26T10:00:00Z"
}
]
},
{
"fromDate": "2025-07-01T00:00:00Z",
"toDate": "2025-07-31T23:59:59Z",
"totalAmount": 0,
"transactions": []
}
]
}
}
},
{
"accountId": "7499D207-F73D-415E-95E7-97D94065FB14",
"bank": "HALIFAX",
"currency": "GBP",
"consents": [
{
"lastUpdateAt": "2025-07-22T00:00:00Z",
"status": "ACTIVE",
"createdAt": "2025-06-22T00:00:00Z",
"expiresAt": "2025-09-22T00:00:00Z"
}
],
"income": {
"statistics": {
"totalAmount": 1700.0,
"MONTHLY": {
"average": 425,
"standardDeviation": 430.84
}
},
"period": {
"MONTHLY": [
{
"fromDate": "2025-04-01T00:00:00Z",
"toDate": "2025-04-30T23:59:59Z",
"totalAmount": 0,
"transactions": []
},
{
"fromDate": "2025-05-01T00:00:00Z",
"toDate": "2025-05-31T23:59:59Z",
"totalAmount": 950.0,
"transactions": [
{
"incomeType": "Salary",
"totalAmount": 200.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-05-02T10:00:00Z"
},
{
"incomeType": "State Pension",
"totalAmount": 750.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-05-02T10:00:00Z"
}
]
},
{
"fromDate": "2025-06-01T00:00:00Z",
"toDate": "2025-06-30T23:59:59Z",
"totalAmount": 750.0,
"transactions": [
{
"incomeType": "State Pension",
"totalAmount": 750.0,
"frequency": "monthly",
"quantity": 1,
"lastPaymentDate": "2025-06-02T10:00:00Z"
}
]
},
{
"fromDate": "2025-07-01T00:00:00Z",
"toDate": "2025-07-31T23:59:59Z",
"totalAmount": 0,
"transactions": []
}
]
}
}
}
]
}
}
}
}
Parameter list:
data.insights.AFFORDABILITY
| Field | Type | Description |
|---|---|---|
| insight | string | Always AFFORDABILITY |
| fromDate | string | Start date for the insight period (ISO 8601). |
| toDate | string | End date for the insight period (ISO 8601). |
| assessableIncome | object | Overall assessable income details (see below). |
| accounts | array | Individual account income breakdowns (see below). |
Assessable Income
| Field | Type | Description |
|---|---|---|
| qualifyingIncomeTypes | array | List of income types considered in this assessment (e.g. "Salary", "State Pension", "Gig", "Other income", "Gambling"). |
| statistics | array[Assessable Income Statistics] | Cross‑account income statistics, grouped by currency. |
| period | Assessable Income Period | Period‑based assessable income, grouped by currency. |
Assessable Income Statistics
| Field | Type | Description |
|---|---|---|
| currency | string | 3‑letter ISO currency code (e.g. "GBP", "EUR"). |
| MONTHLY | Statistics | Statistical summary for this currency on a monthly basis. |
Statistics
| Field | Type | Description |
|---|---|---|
| average | number | Mean income amount for the specified period. |
| standardDeviation | number | Measures the dispersion of income amounts around the mean, indicating income stability. |
Assessable Income Period
| Field | Type | Description |
|---|---|---|
| <Period> | array[Assessable Income Period Data] | Keyed by period type. Example uses MONTHLY. |
Assessable Income Period Data
| Field | Type | Description |
|---|---|---|
| fromDate | string | Month period start date (ISO 8601). |
| toDate | string | Month period end date (ISO 8601). |
| byCurrency | array[Assessable Income Amount] | List of income by currency. |
Assessable Income Amount
| Field | Type | Description |
|---|---|---|
| currency | string | 3‑letter ISO currency code. |
| amount | number | Total assessable income in this currency for the period bucket. |
Account
| Field | Type | Description |
|---|---|---|
| accountId | string | Unique identifier of the account. |
| bank | string | Name of the bank. |
| currency | string | Account currency code (ISO 4217). |
| consents | array[Consent] | List of consent status objects (see below). |
| income | Account Income | Income statistics and monthly breakdown. |
Consent
| Field | Type | Description |
|---|---|---|
| lastUpdateAt | string | Last consent update (ISO 8601). |
| status | string | Consent status, e.g. "ACTIVE". |
| createdAt | string | Consent creation date. |
| expiresAt | string | Consent expiry date. |
Account Income
| Field | Type | Description |
|---|---|---|
| statistics | Account Income Statistics | Aggregate statistics for this account. |
| period | Account Income Period | Period‑based breakdown with income "transactions". |
Account Income Statistics
| Field | Type | Description |
|---|---|---|
| totalAmount | number | Account-level total income calculated. |
| MONTHLY | Statistics | Monthly statistical summary for this account. |
Account Income Period
| Field | Type | Description |
|---|---|---|
| <Period> | array[Account Income Period Data] | Keyed by period type. Example uses MONTHLY |
Account Income Period Data
| Field | Type | Description |
|---|---|---|
| fromDate | string | Month period start. |
| toDate | string | Month period end. |
| totalAmount | number | Total income for the period. |
| transactions | array[Income Transaction] | Breakdown by income source (see below). |
Income Transaction
| Field | Type | Description |
|---|---|---|
| incomeType | string | Classified income type (e.g. "Salary", "Gig", "State Pension", "Private Pension", "Benefits", "Other income", "Gambling"). |
| totalAmount | number | Total for this incomeType for the period. |
| frequency | string | Payment frequency (e.g., "monthly", "weekly", "irregular"). |
| quantity | number | Number of occurrences in period. |
| lastPaymentDate | string | Most recent payment date (ISO 8601). |
Notes:
- All dates must be ISO 8601 UTC format.
- The structure is extensible for additional income types/currencies.
- For monthly statistics and per-period reporting, multiple objects in arrays may be present for rolling periods, currencies, or new income sources.
- Amounts use the corresponding currency code at each level.
Updated 2 months ago