Account Insights
Overview
Account Insights analyses the transactions on a customer's linked accounts and returns a breakdown by the sections you select — overall account activity, POS, and e-commerce. For the POS and e-commerce sections it also compares each month's sales against a floor you set, reporting how many months fell below it, so you can judge how often their revenue fell short.
Prerequisites
- Authentication: Obtain an access token using the Client Credentials flow (see Getting Started → Authentication). Use scope
account_insightswhen generating the token. - Open Banking Prerequisites: Create an Accounts Link for the target institution and keep the resulting
AccountsLinkId(see Getting Started → Open Banking Prerequisites). - Subscription: Subscribe to Account Insights in your chosen environment.
AccountInsights
POST
https://test.api.neotek.sa/open-banking/v1/account-insightsSandbox URL · in Production call https://api.neotek.sa
Body — required as a whole:
| Parameter | Required | Description |
|---|---|---|
psu_id | Required | the Payment Service User id: the identifier you assign to the customer in your own system. Use the same id you sent when creating the accounts link, since that is how Neotek resolves which consented accounts to return |
account_link_id | Required | which consent to analyse: the id returned when creating the accounts link. One consent covers one bank's linked accounts |
transaction_amount_threshold_in_sar | Required | the revenue floor in SAR. In the POS and e-commerce sections, each month's sales are compared against it and the count of months below it is returned in validation_details.number_of_months_with_total_amount_less_threshold |
filters | Required | which sections to return, as an array: account, pos, ecommerce. Each maps to one top-level key in the response |
from_date | Optional | start of the analysis period |
to_date | Optional | end of the analysis period |
account_ids | Optional | restrict the analysis to specific accounts, using AccountId values from ListProfileAccounts. Omit to cover every account on the link |
Headers:
| Parameter | Required | Description |
|---|---|---|
authorization | Required | Bearer <ACCESS_TOKEN>, with scope account_insights |
content-type | Required | application/json |
x-request-id | Optional | an RFC 4122 UUID you generate; quote it when raising a support ticket |
cURL
curl -X POST 'https://test.api.neotek.sa/open-banking/v1/account-insights' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "psu_id": "PTP100", "account_link_id": "2631", "transaction_amount_threshold_in_sar": 10000000000, "filters": ["pos", "ecommerce", "account"]}'Response (trimmed to one account, one month per list)
JSON
{ "accounts_insights": { "bank_name": { "ar": "البنك السعودي للاستثمار", "en": "The Saudi Investment Bank" }, "customer_name": "john", "accounts": [ { "currency": "SAR", "number_of_reported_months": 23, "iban": "SA1234567894123356789362", "account_number": "123356789362", "oldest_transaction_date": "2024-08-03", "current_year_metrics": { "current_year_average_amount": 20797.67, "current_year_total_credit_amount": 249572.02, "current_year_total_debit_amount": 37413.1, "current_year_average_credit_amount_for_last_4_months": 16657.12, "current_year_total_credit_amount_for_last_4_months": 66628.49 }, "last_year_metrics": { "last_year_average_amount": 23268.76, "last_year_total_credit_amount": 279225.14, "last_year_total_debit_amount": 64489.47 }, "current_year_list": [ { "month_year": "6-2026", "total_credit_amount": 17927.32, "number_of_credit_transactions": 2, "average_credit_amount": 8963.66 } ] } ] }, "pos_transactions_insights": [ { "number_of_reported_months": 23, "merchant_name": "john", "registration_num": null, "city_name": null, "oldest_merchant_added_at_date": "2024-08-27", "iban": "SA1234567894123356789362", "account_number": "123356789362", "monthly_details_list": [ { "month_year": "6-2026", "number_of_transactions": 1, "total_amount": 16143.61, "highest_transaction_amount": 16143.61, "lowest_transaction_amount": 16143.61, "average_transaction_amount": 16143.61 } ], "analysis_details": { "total_number_of_yearly_transactions": 11, "total_amount_of_yearly_transactions": 208574.74, "average_monthly_amount": 18961.34 }, "validation_details": { "sum_of_sales_last_three_months": 33595.92, "number_of_months_with_total_amount_less_threshold": 23, "total_account_yearly_transactions_amount": 426894.59 } } ]}Errors
| Code | Status | Cause and Action |
|---|---|---|
400 | Bad Request | Invalid or missing request fields. Check the error Code and Path. Common: NTSP.ERROR.400.349 = PSUId is mandatory. |
401 | Unauthorized | Token missing, expired, or invalid. Refresh the bearer token and retry. |
403 | Forbidden | No valid subscription or insufficient scope. Verify client credentials and that the correct scope is included for the service being called. |
405 | Method Not Allowed | Wrong HTTP verb for this endpoint. Check the endpoint specification. |
406 | Not Acceptable | Accept header mismatch. Use application/json. |
429 | Too Many Requests | Rate limit exceeded. Wait the number of seconds in the Retry-After response header before retrying. |
500 | Internal Server Error | Unexpected server error. Retry with exponential backoff. Include x-request-id when raising a support ticket. |
Ready to build with Account Insights?
Create a sandbox app, grab your credentials, and make your first call in minutes.