Fetching retail bank data

This guide describes how to get data for retail bank accounts.

The APIs

There are a few things you should know about the APIs:

• The corporate data product supports 3 APIs: accounts, transactions and balances.
• The V2 UAE APIs are built so that they require minimal changes in your code to support V2 APIs for our other regions (KSA, as of now)
• The APIs use pagination so you will need to support that in your integration
• For any of the APIs, if you pass verbose=true as a query parameter, in addition to receiving the data in the standardised format for all regions, you will receive the data in the regional format in the field regional_data (check the Retail data API reference for more detail)

Fetch identity data

Once you have an entity_id you can now make calls to /data/v2/identity endpoint (see Retail data identity API reference).

📘

The use of the identity endpoint incurs an additional charge. Please speak to your Sales representative for more info or contact us under [email protected].

Fetch accounts data

📘

There are cases when an account will not be returned by our API, such as:

• Unsupported account types (any account type outside Current, Savings, Credit Cards)
• Loan/mortgage/investment accounts
• Inactive accounts
• If there is an issue on the bank side where we do not receive the full list of accounts

Once you have an entity_id you can also make calls to /data/v2/accounts endpoint (see Retail data accounts API reference). This is necessary for you to make calls to transactions and balances API.

Accounts request

curl -X GET 'https://sandbox.leantech.me/data/v2/accounts?entity_id=3d586d40-04d9-4657-80b7-65bb8cce1e9a&verbose=true' \
    --header 'Content-Type: application/json' \
    --header 'lean-app-token: YOUR_APP_TOKEN' \

Accounts response

{
	"status": "OK",
	"data": {
		"accounts": [
			{
				"account_id": "142c5989-61e7-49e8-a622-ee850a4262f2",
				"status": "ENABLED",
				"status_update_date_time": null,
				"currency": "AED",
				"account_type": "PERSONAL",
				"account_sub_type": "SAVINGS",
				"nickname": "SAVINGS ACCOUNT",
				"opening_date": null,
				"account": [
					{
						"scheme_name": "IBAN",
						"identification": "AE440260000215588955401",
						"name": null
					},
					{
						"scheme_name": "BBAN",
						"identification": "0215588955401",
						"name": null
					}
				],
				"servicer": null,
				"description": "SAVINGS ACCOUNT",
				"maturity_date": null,
				"regional_data": {
					"standard": "ARE.LEAN.V1",
					"data": {
						"account_id": "142c5989-61e7-49e8-a622-ee850a4262f2",
						"account_number": "0215588955401",
						"name": "SAVINGS ACCOUNT",
						"currency_code": "AED",
						"type": "SAVINGS",
						"iban": "AE440260000215588955401",
						"credit": null
					}
				}
			}
		],
		"page": {
			"number": 0,
			"size": 1,
			"total_elements": 1,
			"total_pages": 1
		},
		"type": "accounts"
	},
	"results_id": "32ad4dd7-f1e2-4c7c-889b-298a69cfea9b",
	"message": "Data successfully retrieved",
	"meta": null,
	"timestamp": "2023-07-13T08:53:47.772261577Z",
	"status_detail": null
}

After making an /accounts/ call you should save the account_id field from the response, as this will be used to make Balance and Transaction calls on the associated accounts.

Fetch balances and transactions data

Once you have an account_id for a specific account, you can now make calls for balance and transaction data.

Balances returns an overview of the cash position and type of the account (see Retail data balances API reference). Transactions returns an array of transaction objects (see Retail data transactions API reference), you can also request for this to be returned with categorisation with the insights: true flag (more details on categorisation see our Categorisation guide).