Enables Merchants/Operators to view a user's bank statement, detailing all transactions within a specified time period.
Potential Use Cases:
- Assess financial health
- KYC
- Transactional behaviour
- AML/DD
- Other operational processes
The Insights webhook is HTTPS post request and a typical example of the request body is as follows:
{
"type": "INSIGHTS",
"data": {
"metadata": {
"merchantId": "merchantId123",
"customerId": "customer123",
"reference": "customer123",
"citizenTransactionId": "transactionId123",
"merchantTradingName": "Merchant 123 Ltd"
},
"insightGroup": {
"id": "insightGroupId123",
"name": "Bank Statement Insight Group",
"insights": [
"BANK_STATEMENT"
],
"period": [
"MONTHLY"
],
"fromDate": "2026-01-01T00:00:00Z",
"toDate": "2026-02-10T13:44:44.445012675Z"
},
"insights": {
"BANK_STATEMENT": {
"fromDate": "2026-01-01T00:00:00Z",
"toDate": "2026-02-10T13:44:44.445012675Z",
"accounts": [
{
"consents": [
{
"consentId": "consentId123",
"status": "ACTIVE",
"lastUpdateAt": "2026-02-10T13:44:44.97273Z",
"expiresAt": "2026-05-11T13:44:42.804Z"
}
],
"bank": "HALIFAX",
"accountType": "CURRENT",
"accountHolderName": "Mr First Last",
"fromDate": "2026-01-01T00:00:00Z",
"toDate": "2026-02-10T13:44:44.445012675Z",
"accountNumber": "12345678",
"sortCode": "123456",
"currency": "GBP",
"moneyIn": 25230.46,
"moneyOut": 25217,
"closingBalance": 93.37,
"openingBalance": 79.98,
"statements": {
"period": {
"MONTHLY": [
{
"fromDate": "2026-02-01T00:00:00Z",
"toDate": "2026-02-28T23:59:59Z",
"description": "2026-02",
"moneyIn": 500.00,
"moneyOut": 474.92,
"closingBalance": 27.80,
"openingBalance": 2.72,
"transactions": [
{
"date": "2026-02-04T00:00:00Z",
"description": "Transfer to friend",
"category": "OTHER",
"paymentType": "PAYMENT",
"amount": -400,
"balanceAfterTransaction": 27.8
},
{
"date": "2026-02-04T00:00:00Z",
"description": "Bowling",
"category": "OTHER",
"paymentType": "PAYMENT",
"amount": -16,
"balanceAfterTransaction": 427.8
},
{
"date": "2026-02-04T00:00:00Z",
"description": "Credit Card Payment",
"category": "OTHER",
"paymentType": "PAYMENT",
"amount": -58.92,
"balanceAfterTransaction": 443.80
},
{
"date": "2026-02-04T00:00:00Z",
"description": "Transfer from friend",
"category": "OTHER",
"paymentType": "TRANSFER",
"amount": 500,
"balanceAfterTransaction": 502.72
}
]
},
{
"fromDate": "2026-01-01T00:00:00Z",
"toDate": "2026-01-31T23:59:59Z",
"description": "2026-01",
"moneyIn": 19.00,
"moneyOut": 501.47,
"closingBalance": 2.72,
"openingBalance": 469.19,
"transactions": [
{
"date": "2026-01-29T00:00:00Z",
"description": "TRAIN FARE",
"category": "OTHER",
"paymentType": "PAYMENT",
"amount": -32,
"balanceAfterTransaction": 2.72
},
{
"date": "2026-01-26T00:00:00Z",
"description": "PARKING",
"category": "OTHER",
"paymentType": "PAYMENT",
"amount": -5.5,
"balanceAfterTransaction": 34.72
},
{
"date": "2026-01-23T00:00:00Z",
"description": "PAYPAL",
"category": "OTHER",
"paymentType": "PAYMENT",
"amount": 19,
"balanceAfterTransaction": 40.22
},
{
"date": "2026-01-16T00:00:00Z",
"description": "APPLE.COM/BILL",
"category": "OTHER",
"paymentType": "PAYMENT",
"amount": -0.99,
"balanceAfterTransaction": 21.22
},
{
"date": "2026-01-16T00:00:00Z",
"description": "GYM MEMBERSHIP",
"category": "OTHER",
"paymentType": "DIRECT_DEBIT",
"amount": -23.99,
"balanceAfterTransaction": 22.19
},
{
"date": "2026-01-12T00:00:00Z",
"description": "Flight Booking",
"category": "OTHER",
"paymentType": "PAYMENT",
"amount": -420,
"balanceAfterTransaction": 49.19
}
]
}
]
}
}
}
],
"insight": "BANK_STATEMENT"
}
}
}
}
| Field | Type | Description |
|---|
| insight | string | Always BANK_STATEMENT |
| fromDate | string | Period start date (ISO 8601). |
| toDate | string | Period end date (ISO 8601). |
| accounts | array[Account] | List of account objects |
| Field | Type | Description |
|---|
| consents | array[Consent] | List of consent objects (with status and expiry). |
| bank | string | Bank name (e.g., "CITIZEN_TEST_BANK"). |
| accountType | string | Type of account (e.g., "CURRENT"). |
| accountHolderName | string | Name of the account holder. |
| fromDate | string | Account statement period start (ISO 8601). |
| toDate | string | Account statement period end (ISO 8601). |
| accountNumber | string | Bank account number. |
| sortCode | string | Bank sort code (UK format). |
| currency | string | Currency (ISO 4217 code, e.g., GBP). |
| moneyIn | number | Total incoming transactions for period. |
| moneyOut | number | Total outgoing transactions for the period. |
| closingBalance | number | Balance at the end of the period. |
| openingBalance | number | Balance at the start of the period. |
| statements | Statements | Monthly statement breakdown (see below). |
| Field | Type | Description |
|---|
| id | string | Unique consent ID. |
| status | string | Status ("ACTIVE", etc.). |
| lastUpdateAt | string | Last update timestamp (ISO 8601). |
| expiresAt | string | Expiry timestamp (ISO 8601). |
| Field | Type | Description |
|---|
| period | Bank Statement Period | Statement data broken down by requested period(s). |
| Field | Type | Description |
|---|
| /<Period> | array[Bank Statement Period Data] | Keyed by period type. Supported values include only MONTHLY |
| Field | Type | Description |
|---|
| fromDate | string | ISO 8601 UTC start date for this period bucket. |
| toDate | string | ISO 8601 UTC end date for this period bucket. |
| description | string | Human‑readable period label, e.g. "2025-09". |
| moneyIn | number | Total credits (sum of positive transactions) within this bucket. |
| moneyOut | number | Total debits (sum of negative transactions) within this bucket. |
| openingBalance | number | Balance at the start of the bucket. |
| closingBalance | number | Balance at the end of the bucket. |
| transactions | array[Transaction] | List of individual transactions in this bucket. |
| Field | Type | Description |
|---|
| date | string | ISO 8601 UTC transaction timestamp. |
| description | string | Bank/narrative description (e.g. merchant name or reference). |
| category | string | null | Transaction category, e.g. "GAMBLING", "OTHER", or null if uncategorised. |
| paymentType | string | Transaction type as returned or normalised, e.g. "TRANSFER", "DIRECT_DEBIT", "STANDING_ORDER". |
| amount | number | Transaction amount; positive for money in, negative for money out. |
| balanceAfterTransaction | number | Account balance immediately after this transaction is applied. |
Notes:
- All dates/times formatted ISO 8601 UTC (e.g., "2025-09-26T07:32:34.159233Z").
- Large arrays are truncated for brevity in documentation; real requests may contain more items.
- For additional categories and payment types, reference the enumeration in your API documentation.
- All monetary amounts are reported in the specified account currency.
