Balance

Returns a high-level view of the customer’s balance over time.

Potential Use Cases:

Understand current balance
Monitor balance trends

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": "Balance Insight",
      "insights": [
        "BALANCE"
      ],
      "period": [
        "MONTHLY"
      ],
      "fromDate": "2025-06-28T09:32:33.440188Z",
      "toDate": "2025-09-26T09:32:33.440206Z"
    },
    "insights": {
      "BALANCE": {
        "insight": "BALANCE",
        "fromDate": "2025-06-28T09:32:33.440188Z",
        "toDate": "2025-09-26T09:32:33.440206Z",
        "crossAccount": {
          "balance": {
            "period": {
              "MONTHLY": [
                {
                  "fromDate": "2025-09-01T00:00:00Z",
                  "toDate": "2025-09-26T09:32:33.440206Z",
                  "totalBalance": [
                    {
                      "currency": "GBP",
                      "closingAmount": 97.72
                    }
                  ]
                }
              ]
            }
          }
        },
        "accounts": [
          {
            "accountId": "d73f1b9d-5b2f-4d61-b4dc-72ec697cd40b",
            "bank": "CITIZEN_TEST_BANK",
            "currency": "GBP",
            "consents": [
              {
                "lastUpdateAt": "2025-09-26T09:32:33.852652Z",
                "status": "ACTIVE",
                "createdAt": "2025-09-26T09:32:33.126Z",
                "expiresAt": "2025-12-25T10:32:33.125Z"
              }
            ],
            "balance": {
              "period": {
                "MONTHLY": [
                  {
                    "fromDate": "2025-09-01T00:00:00Z",
                    "toDate": "2025-09-26T09:32:33.440206Z",
                    "closingAmount": 97.72
                  }
                ]
              }
            }
          },
          {
            "accountId": "ad0e5d20-3be6-4dcb-a671-3c5fc3e72c96",
            "bank": "CITIZEN_TEST_BANK",
            "currency": "EUR",
            "consents": [
              {
                "lastUpdateAt": "2025-09-26T09:32:33.852805Z",
                "status": "ACTIVE",
                "createdAt": "2025-09-26T09:32:33.126Z",
                "expiresAt": "2025-12-25T10:32:33.125Z"
              }
            ],
            "balance": {
              "period": {
                "MONTHLY": [
                  {
                    "fromDate": "2025-09-01T00:00:00Z",
                    "toDate": "2025-09-26T09:32:33.440206Z",
                    "closingAmount": 0
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

Balance Parameters

data.insights.BALANCE

Field	Type	Description
insight	string	The insight key ("BALANCE").
fromDate	string	Start date (ISO 8601) for this insight's period.
toDate	string	End date (ISO 8601) for this insight's period.
crossAccount	Cross‑Account Balance	Aggregation for all accounts (see below).
accounts	array[Account]	List of individual account balance objects.

Cross‑Account Balance

Field	Type	Description
balance	Cross‑Account Balance Period	Total balances across all accounts, broken down by period.

Cross‑Account Balance Period

Field	Type	Description
<Period>	array[Cross‑Account Period Data]	Cross account balance broken down by period. Period can be MONTHLY, WEEKLY, DAILY

Cross‑Account Period Data

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.
totalBalance	array[Total Balance]	List of total balances by currency for this bucket.

Total Balance

Field	Type	Description
currency	string	3‑letter ISO currency code, e.g. "GBP", "EUR".
closingAmount	number	Total closing balance across all accounts in this currency at the end of the bucket.

Account

Field	Type	Description
accountId	string	Unique identifier for this account within Yaspa.
bank	string	Bank identifier, e.g. "CITIZEN_TEST_BANK".
currency	string	3‑letter ISO currency code for this account (e.g. "GBP", "EUR").
consents	array[Consent]	List of consent records used to access this account.
balance	Account Balance Period	Account‑level balances broken down by period.

Consent object

Field	Type	Description
lastUpdateAt	string	ISO timestamp of the latest consent update.
status	string	Consent status, e.g. "ACTIVE".
createdAt	string	ISO timestamp when the consent was created.
expiresAt	string	ISO expiry timestamp for the consent.

Account Balance Period

Field	Type	Description
<Period>	Account Balance Period Data	Periodised balance data for the account.

Account Balance Period Data

Field	Type	Description
fromDate	string	ISO 8601 UTC start date for this account's period bucket.
toDate	string	ISO 8601 UTC end date for this account's period bucket.
closingAmount	number	Account closing balance at the end of this period bucket (in account currency).

Notes:

All timestamps should be provided in ISO 8601 UTC.
Amount values use the specified currency.
Arrays can include multiple entries covering different periods, currencies, or accounts as shown.
Only key fields are listed; extend as your insight model evolves.