Analyze customer spending patterns and expense behavior using consented Open Banking transaction data
Expense Check service provides detailed insights into a customer's outgoing transactions across one or more accounts. It identifies spending patterns, categorizes expenses, tracks cash outflows over time, and generates expense analytics that can support affordability assessments, budgeting solutions, risk analysis, and customer financial profiling.
Expense Check service analyzes debit transactions and outgoing payments within a specified period to provide a comprehensive view of customer spending behavior.
Using this service, you can:
The service returns transaction-level spending data along with aggregated expense insights and category breakdowns.
Access to this API requires a valid consent that has been authorized by the customer.
consentId must refer to an active and authorized consentAuthorization: Bearer headerThis API can only be accessed using a valid and active consent. Before accessing this service, ensure that a consent has been created and authorized with the required useCaseType and permissions.
The consent must include the appropriate useCaseType and permission values that allow access to the corresponding financial data services.
If you do not already have a consent with the required configuration, you must first create one using the Create Consent API and ensure that it is successfully authorized. Once the consent becomes active, the generated consentId can be used to access this API service.
Scope | useCaseType | Permissions |
|---|---|---|
To access Expense Check service under Data Use Case APIs |
|
|
Endpoint URL | Method |
|---|---|
| GET |
The following headers must be included when calling the Basic Income Check API.
Header parameter | Description |
|---|---|
| Access token used to authenticate the API request |
curl --request GET \
--url 'https://obsandbox.onesingleview.com/v2/api/observice/expenseCheck?dateTimeStamp=2023-06-14T17%3A51%3A03&requestID=db35902b-806a-4141-b1e2-e93f60c82f62&merchantId=APIU-300356&insights=true&expenseCheck=true&fromDate=2016-01-01T10%3A40%3A00%2B02%3A00&toDate=2025-12-31T10%3A40%3A00%2B02%3A00&timeLine=byDay&bankCode=SVMOB1&consentId=urn%3ASVMOB%3Akac-cd3b9a37-eb97-4a70-b268-38af9f2950b1' \
--header 'accept: application/json'Request parameters
Parameters | Requirement | Description | Data type | Data validation |
|---|---|---|---|---|
dateTimeStamp | Mandatory | Indicates the date and time when the request is created | Date | ISO 8601 format |
requestID | Mandatory | Unique identifier for the request used for tracking and traceability | Alphanumeric | UUID format |
merchantID | Mandatory | Identifier assigned to the merchant or client application initiating the request | String |
|
insights | Mandatory | Indicates that analytical insights should be included in the response |
|
|
expenseCheck | Mandatory | Specification of data use case API |
|
|
fromDate | Mandatory | Start date of the analysis period | Date | ISO 8601 format |
toDate | Mandatory | End date of the analysis period | Date | ISO 8601 format |
timeLine | Mandatory | Timeline aggregation interval | Enum |
|
bankCode | Mandatory | Unique bank identifier code | Enum |
|
consentId | Mandatory | Unique identifier of the consent | String |
|
{
"success": true,
"payload": [
{
"code": "",
"consentId": "",
"data": {
"account": [
{
"accountId": "dd11ad81-e172-4121-b6fe-2461a5cfff52",
"accountHolderName": "Habib Al-Sagga",
"accountHolderShortName": "Habib Al-Sagga",
"status": "Active",
"currency": "SAR",
"nickname": "Habib Al-Sagga",
"accountType": "Personal",
"accountSubType": "",
"accountIdentifiers": [
{
"identificationType": "KSAOB.IBAN",
"identification": "00000250000002",
"name": "Habib Al-Sagga"
}
],
"servicer": {
"identificationType": "KSAOB.BICFI",
"identification": "10000109010101"
},
"statusUpdateDateTime": "2023-07-11T07:48:38.115Z",
"description": "Account sub-type description",
"openingDate": "2022-09-15T07:48:38.115Z",
"maturityDate": "2024-05-07T07:48:38.115Z",
"transactions": [
{
"transactionId": "1b3a6d00-7c18-4b51-950a-0f7633099058",
"transactionDateTime": "2025-11-03T06:30:00",
"transactionReference": "20ac1685-cd48-4a76-a13d-3a689d54454b",
"transactionType": "KSAOB.LocalBankTransfer",
"subTransactionType": "KSAOB.Deposit",
"paymentModes": "KSAOB.Offline",
"creditDebitIndicator": "KSAOB.Credit",
"status": "KSAOB.Booked",
"transactionMutability": "KSAOB.Mutable",
"bookingDateTime": "2025-11-03T06:30:00",
"valueDateTime": "2025-11-03T06:30:00",
"amount": {
"amount": "3652.00",
"currency": "SAR"
},
"chargeAmount": {
"amount": "0.00",
"currency": "SAR",
"chargeIncluded": false
},
"balance": {
"creditDebitIndicator": "KSAOB.Credit",
"type": "KSAOB.ClosingAvailable",
"amount": {
"amount": "2321.00",
"currency": "SAR"
}
},
"merchantDetails": {
"merchantName": "Business Services Not Elsewhere Classified",
"merchantCategoryCode": "7399",
"merchantId": 1234
},
"localTimeZone": "UTC+03:00",
"terminalId": 12345678,
"chargeAmountVat": {
"amount": "71.5806",
"currency": "SAR"
},
"flags": [
"KSAOB.Payroll"
],
"cardInstrument": {
"cardSchemeName": "KSAOB.AmericanExpress",
"instrumentType": "KSAOB.ApplePay",
"name": "test",
"identification": "1234********4321"
},
"creditorAccount": [
{
"identificationType": "KSAOB.IBAN",
"identification": "string",
"name": "Sahara Petrochemicals"
}
],
"debtorAccount": {
"identificationType": "KSAOB.IBAN",
"identification": "string",
"name": "Yansab"
},
"transactionInformation": "SALARY",
"bankTransactionCode": {
"domain": "domain",
"domainCode": "domainCode",
"family": "family",
"familyCode": "familyCode",
"subFamily": "subFamily",
"subFamilyCode": "subFamilyCode"
},
"proprietaryBankTransactionCode": {
"code": "code",
"issuer": "issuer"
},
"creditorAgent": {
"identificationType": "KSAOB.BICFI",
"identification": "KSAOB.BICFI",
"postalAddress": {
"addressType": "KSAOB.Business",
"streetName": "streetName",
"buildingNumber": "1234",
"postalCode": "postCode",
"city": "townName",
"country": "SA",
"shortAddress": "address",
"unitNumber": 1234,
"secondaryNumber": "1234",
"district": "district"
},
"name": "Ali"
},
"debtorAgent": {
"identificationType": "KSAOB.BICFI",
"identification": "string",
"postalAddress": {
"addressType": "KSAOB.Business",
"streetName": "streetName",
"buildingNumber": "1234",
"postalCode": "postCode",
"city": "townName",
"country": "SA",
"shortAddress": "address",
"unitNumber": 1234,
"secondaryNumber": "1234",
"district": "district"
},
"name": "string"
},
"billDetails": {
"billerId": 100004,
"billNumber": "1234",
"billPaymentType": "KSAOB.Renewal"
}
}
]
}
]
},
"links": {
"self": "https://rs1.sandbox.sabb.com/open-banking/account-information/2022.11.01-final-errata2/accounts"
},
"meta": {
"totalPages": 1
},
"insights": {
"startDate": "2016-01-01T10:40:00+02:00",
"endDate": "2025-12-31T10:40:00+02:00",
"currency": "SAR",
"cashOut": {
"amount": 123094,
"currency": "SAR",
"count": 67
},
"yesterDayCashOut": {
"amount": 0,
"currency": "SAR",
"count": 0
},
"cashOutTimeLine": [
{
"date": "2025 11 03",
"count": 0,
"amount": 0,
"currency": "SAR"
}
],
"cashOutCategories": [
{
"category": "KSAOB.POS",
"count": 27,
"amount": 44941,
"currency": "SAR"
}
],
"bankCode": "SVMOB1"
}
}
],
"overAllTxns": {
"cashOut": {
"count": 67,
"amount": 123094,
"currency": "SAR"
},
"cashOutCategories": [
{
"name": "KSAOB.POS",
"count": 27,
"amount": 44941,
"percentage": 36.50949680731799,
"currency": "SAR"
}
],
"cashOutTimeLine": [
{
"date": "2025 11 03",
"count": 8,
"amount": 19887,
"currency": "SAR"
}
],
"yesterDayCashOut": {
"count": 0,
"amount": 0,
"currency": "SAR"
}
}
}Response parameters
Parameter | Description |
|---|---|
success | Process success status represented as |
payload | Payload tag carrying response information |
code | Unique bank code identification |
data | Tag carrying accounts and transactions data included in the response |
accountId | Unique account identification |
transactions | Tag carrying account transactions information |
transactionId | Unique transaction identification |
transactionDateTime | Time and date of the transaction executed |
transactionReference | Unique transaction reference details |
transactionType | Type of transaction |
subTransactionType | Sub-type of the transaction |
paymentModes | Mode of the payment |
creditDebitIndicator | Credit or debit indicator for the transaction |
status | Status of the transaction |
transactionMutability | Mutability factor of the transaction |
bookingDateTime | Date and time of booking the transaction |
valueDateTime | Date and time of transaction value |
amount | Tag carrying transaction amount information |
amount | Transaction amount |
currency | Default currency of the account in which the transaction amount is indicated |
chargeAmount | Tag carrying transaction charges information |
amount | Total amount charged for the transaction |
currency | Default currency of account in which the transaction charge amount is indicated |
chargeIncluded | Indicates if the charge amount is included in transaction amount as |
balance | Balance info after the transaction |
creditDebitIndicator | Indicates whether the balance is a credit or a debit balance |
type | Indicator type details |
amount | Tag carrying balance amount information |
amount | Available amount balance |
currency | Currency in which the balance is indicated |
merchantDetails | Tag carrying merchant details |
merchantName | Name of the merchant |
merchantCategoryCode | Assigned merchant category code |
merchantId | Unique merchant identification |
localTimeZone | Local time zone information |
terminalId | Unique terminal identification |
chargeAmountVat | Tag carrying VAT amount charges and details |
amount | VAT amount charged |
currency | Currency of VAT amount charged indicated |
flags | Tag carrying flags as array of strings |
cardInstrument | Tag carrying card details |
cardSchemeName | Scheme name description of the card |
instrumentType | Type of instrument used for the card payment |
name | Name on the card |
identification | Unique card identification |
creditorAccount | Tag carrying creditor account information |
debtorAccount | Tag carrying debtor account information |
identificationType | Type of identification of the account |
identification | Account identification details |
name | Name of the account holder |
transactionInformation | Details of the transaction information |
bankTransactionCode | Tag carrying transaction bank codes |
domain | Domain details |
domainCode | Domain code |
family | Domain family details |
familyCode | Domain family code |
subFamily | Domain sub-family details |
subFamilyCode | Domain sub-family code |
proprietaryBankTransactionCode | Tag representing proprietary bank transaction code and details |
code | Unique proprietary transaction code |
issuer | Name of the issuer of the code |
creditorAgent | Tag carrying creditor agent information |
debtorAgent | Tag carrying debtor agent information |
identificationType | Type of identification of the creditor/debtor account |
identification | Unique identification details of the creditor/debtor account |
postalAddress | Postal address of the creditor/debtor account |
addressType | Address type on the creditor/debtor account |
streetName | Street name on the creditor/debtor account |
buildingNumber | Building number of the creditor/debtor account |
postalCode | Postal code on the creditor/debtor |
city | City of the creditor/debtor |
country | Country of the creditor/debtor |
shortAddress | Short address of the creditor/debtor |
unitNumber | Unit number of the creditor/debtor |
secondaryNumber | Secondary number of the creditor/debtor |
district | District of the creditor/debtor |
name | Name of the creditor/debtor |
billDetails | Tag carrying bill details |
billerId | Unique biller identification |
billNumber | Bill number |
billPaymentType | Payment type for the bill |
links | Redirect link |
self | Own link/URL details |
meta | Meta tag |
totalPages | Information displayed in terms of pages |
insights | Tag providing aggregated expense analysis for the specified period |
startDate | Beginning of the analysis period |
endDate | End of the analysis period |
currency | Currency used for the analysis results |
cashOut | Tag summarizing all outgoing funds identified during the analysis period |
amount | Total outgoing funds expensed |
currency | Currency associated with the outgoing funds |
count | Total number of outgoing transactions identified |
yesterDayCashOut | Tag providing a summary of outgoing transactions made during the previous day |
amount | Total outgoing funds during the previous day |
currency | Currency associated with the transactions |
count | Number of outgoing transactions received during the previous day |
cashOutTimeLine | Tag providing a chronological breakdown of outgoing funds |
date | Timeline period |
count | Number of outgoing transactions within the period |
amount | Total outgoing amount during the period |
currency | Currency associated with the transactions |
cashOutCategories | Tag providing grouped expenses by transaction category |
category | Transaction category identified as a destination of expense |
count | Number of transactions within the category |
amount | Total expense amount attributed to the category |
currency | Currency associated with the category |
overAllTxns | Tag providing consolidated expense metrics across all accounts included in the consent |
count | Total number of outgoing transactions across all accounts |
amount | Total outgoing funds across all accounts |
currency | Currency associated with the transactions |