Average Balance
Overview
The Average Balance API computes average daily balances over standard periods (3, 6, 12 months) for a linked account, helping lenders and scoring platforms automate underwriting and cash-flow assessments. It leverages user-consented Open Banking links and returns a concise summary per account.
Prerequisites
- Authentication: Obtain an access token using the Client Credentials flow (see Getting Started → Authentication). Use scope
average_balancewhen generating the token. - Open Banking Prerequisites: Create an Accounts Link for the target institution and wait until it is Active (see Getting Started → Open Banking Prerequisites).
- Subscription: Subscribe to Average Balance in your chosen environment.
GetAverageBalance
GET
https://test.api.neotek.sa/balances/v1/average-balanceSandbox URL · in Production call https://api.neotek.sa
Query parameters:
| Parameter | Required | Description |
|---|---|---|
PSUId | 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 |
AccountsLinkId | Required | the consent id returned when creating the accounts link |
Duration | Required | the period in months: 3, 6 or 12. The response key reflects it, so Duration=6 returns 6_months |
AccountId | Optional | narrow the result to a single consented account, using an AccountId from ListProfileAccounts |
CustomerType | Optional | SME or Retail |
Headers:
| Parameter | Required | Description |
|---|---|---|
authorization | Required | Bearer <ACCESS_TOKEN> |
x-request-id | Optional | — |
cURL
curl -G 'https://test.api.neotek.sa/balances/v1/average-balance' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -d 'PSUId=PTP100' \ -d 'AccountsLinkId=2631' \ -d 'AccountId=ACC-5C9F1F19' \ -d 'Duration=6'Response
JSON
{ "AccountId": "ACC-5C9F1F19", "Average_Balance": { "6_months": "96199.5", "TransactionCount": "13" }}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 Average Balance?
Create a sandbox app, grab your credentials, and make your first call in minutes.