Fetching retail bank data

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

Fetch Identity & Account data

Once you have an entity_id you can now make calls to the /data/v1/identity/ and /data/v1/accounts/ endpoints.

📘
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].

Identity Call & Response:

❗️
The identity product is only supported for retail accounts and not corporate.

curl -X POST 'https://sandbox.leantech.me/data/v1/identity' \
    --header 'Content-Type: application/json' \
    --header 'lean-app-token: YOUR_APP_TOKEN' \
    --data-raw '{
        "entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185"
    }'

{
  "status": "OK",
  "payload": {
      "full_name": "John Doe",
      "mobile_number": "07849720842",
      "gender": "male",
      "national_identity_number": "123456789",
      "birth_date": "1990-09-15",
      "email_address": "[email protected]",
      "address": "140 Tabernacle Street, Shoreditch EC2A 4SD"
  }
}

Accounts Call & Response:

📘
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

curl -X POST 'https://sandbox.leantech.me/data/v1/accounts' \
    --header 'Content-Type: application/json' \
    --header 'lean-app-token: YOUR_APP_TOKEN' \
    --data-raw '{ 
      "entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185" 
    }'

{
  "status": "OK",
  "payload": {
    "accounts": [
      {
          "account_id": "3d586d40-04d9-4657-80b7-65bb8cce1e9a",
          "name": "Mockbank1 Checkings Account",
          "currency_code": "SAR",
          "type": "Checkings",
          "iban": "SA03 8000 0000 6080 1016 7519",
          "bank_identifier": "LEANMB1"
      }, {
          "account_id": "3e9e4289-9e4f-480f-af68-3181cb35218e",
          "name": "Mockbank1 Savings Account",
          "currency_code": "SAR",
          "type": "Savings",
          "iban": "SA03 8000 0000 6080 1635 2788",
          "bank_identifier": "LEANMB1"
      }
    ]
  }
}

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

Fetch Balance and Transaction data

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

Balance returns an overview of the cash position and type of the account.

Transactions returns an array of transaction objects, you can also request for this to be returned with categorization with the insights: true flag.

Balance Call & Response:

curl -X POST 'https://sandbox.leantech.me/v1/balance' \
    --header 'Content-Type: application/json' \
    --header 'lean-app-token: YOUR_APP_TOKEN' \
    --data-raw '{
        "entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185",
        "account_id": "01bb8b3f-8462-470b-b2ed-14eb15b95fa2"
    }'

{
  "status": "OK",
  "payload": {
    "balance": 15035.85,
    "currency_code": "SAR",
    "account_id": "01bb8b3f-8462-470b-b2ed-14eb15b95fa2",
    "account_name": "Mockbank1 Checkings Account",
    "account_type": "Checkings"
  }
}

Transactions Call & Response:

curl -X POST 'https://sandbox.leantech.me/v1/transactions' \
  --header 'Content-Type: application/json' \
  --header 'lean-app-token: YOUR_APP_TOKEN' \
  --data-raw '{
    "entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185",
    "account_id": "01bb8b3f-8462-470b-b2ed-14eb15b95fa2",
    "start_date": "2020-03-01",
    "end_date": "2020-03-15",
    "insights": true
  }'

{
  "status": "OK",
  "payload": {
    "transactions": [
      {
        "id": "01e39a9c-a4ff-3429-a079-968ad1bbb0a3",
        "description": "ALETIHAD CREDIT BUREAU ABU DHABI AE",
        "amount": 84685.18,
        "currency_code": "AED",
        "pending": false,
        "timestamp": "2021-01-31T00:00:00Z",
        "insights": {
          "description_cleansed": "ALETIHAD CREDIT BUREAU ABU DHABI AE",
          "category": "LOANS_AND_INVESTMENTS",
          "category_confidence": 0.99,
          "type": "TRANSFER",
          "type_confidence": 1
        }
      }
    ]
  }
}