Data API Reference

In order to make calls to the Data API you will first require an entity_uuid. If you don't have this already, please see the Link SDK guide to retrieve access to your users' bank entities.

The Data API uses four simple endpoints:

/identity

Verified information about your user submitted as part of their KYC procedures.


/accounts

Accounts connected to the bank entity, there may be multiple accounts in a single entity (e.g. Savings and Checking account). The accounts endpoint gives you an identifier for use in the remaining two endpoints.


/balance

A specific balance for a single account within the bank entity.


/transactions

Returns an array of transaction information related to a specific account within the bank entity.


Authentication

Calls to the Lean Data API uses certificates and mTLS to authenticate requests. You can revoke certificates and download replacements from your Application Dashboard.

Your API certificates carry many privileges, so be sure to keep them secure! Do not share your certificates in publicly accessible areas such as GitHub, client-side code, and so forth.

To use your API certificates, set up a truststore and a keystore for use with an SSL context in your server side requests.

API requests without proper authentication will fail.

Guide to setting up mTLS

Was this section helpful? 

Errors

Lean uses conventional HTTP response codes with requests to help you identify errors and how to rectify them. We also provide a status and message within the body of an error response to indicate how to resolve the error that has occurred.

In general: codes in the 2XX range indicate success, codes in the 4XX range indicate a bad request and codes in the 5XX range indicate something went wrong on our end.

View List of Error Statuses

MISSING_PARAMETERS 400

The request does not have all the required parameters to complete the call.


INVALID_PARAMETERS 400

The request provided invalid parameters.


INSUFFICIENT_PERMISSIONS 403

You do not have the required permissions from your customer to make this call.


USER_UNAUTHORIZED 403

Your customer has revoked a permission required to make this call.


INVALID_CERTIFICATE 403

The certificate on your server has not been recognized.


UNKNOWN_ENTITY 404

The entity_id provided did not match an account in our records.


UNKNOWN_ACCOUNT 404

The account_id provided does not match an account with the entity_id provided.


UNKNOWN_APP_ID 404

The app_id provided has not been recognized by Lean.


UNKNOWN_RESULTS_ID 404

The results_id provided has not been recognized by Lean


RATE_LIMIT_EXCEEDED 429

Rate limit exceeded. Please try again later.


INTERNAL_SERVER_ERROR 500

Something has gone wrong. If you continue to see this error, please get in touch with Lean.

Was this section helpful? 

javascript

HTTP CODE: 400
{
results_id: "139820938109823",
status: "MISSING_PARAMETERS",
message: "The request does not have all the required parameters to complete the call.",
payload: null
meta: {
...meta_data
}
timestamp: "2020-08-08T00:00:00Z"
}

Identity

Required Permissions: identity

The /identity endpoint allows you to retrieve an end user's identity data held by the financial institution.

Request

entity_uuid String

The identifier for your user’s bank entity. This is obtained via the Link SDK


Returns

full_name String

The owner of the entitys full name, taken by the financial institution when setting up their accounts.


mobile_number String

Account holder's mobile number as reported to the financial institution.


gender String

Account holder's sex as reported to the financial institution.


national_identity_number String

Account holder's national identifier number as reported to the financial institution


birth_date String

Account holder’s date of birth. Formatted as a UTC date YYYY-MM-DD


email_address String

Account holder's email address as reported to the financial institution


address String

Account holder's home address as reported to the financial institution


Was this section helpful? 

endpoint

POST https://sandbox.leantech.me/v1/identity

bash

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

javascript

// example response
{
"full_name": "Sandbox user",
"mobile_number": "07849720842",
"gender": "male",
"national_identity_number": "123456789",
"birth_date": "1990-09-15",
"email_address": "sandboxuser1@leantech.me",
"address": "140 Tabernacle Street, Shoreditch EC2A 4SD"
}

Accounts

Required permissions: Accounts

The /accounts endpoint allows you to retrieve a list of all the accounts your customer holds within the financial institution along with their respective information

Request

entity_uuid String

The identifier for your user’s bank entity. This is obtained via the Link SDK


Returns

Requests to the Accounts endpoint return an array of accounts with the following attributes.

account_uuid String

An identifier for the account which is used for the /balance and /transactions endpoints.


name String

The name of the account within the financial instituition


currency_code String

ISO 4217 currency code representing the currency of the balance. A dataset of all countries and their associated codes can be found here.


type String

Type of bank account (e.g. Checking, savings, credit, loan etc.)

View account types

ChargeCard

A credit line that must be paid off in full each month.


CreditCard

Bank issued credit card


CurrentAccount

A standard checking account


Loan

A Loan account


Mortgage

A Mortgage account


PrePaidCard

A prepaid debit card


Savings

A standard savings account


iban String

International Bank Account Number (iban) for the account, if available.


bank_identifier String

How Lean internally refers to the bank. Can be used with the upcoming /bank endpoint

Was this section helpful? 

Endpoint

POST https://sandbox.leantech.me/v1/accounts

bash

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

jsx

// Example response
[
{
"account_uuid": "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_uuid": "3e9e4289-9e4f-480f-af68-3181cb35218e",
"name": "Mockbank1 Savings Account",
"currency_code": "SAR",
"type": "Savings",
"iban": "SA03 8000 0000 6080 1635 2788",
"bank_identifier": "LEANMB1"
}
]

Balance

Required permissions: balance

The /balance endpoint gives you real time balance information of a specific account within the user’s bank entity.

Request

entity_uuid String

The identifier for your user’s bank entity. This is obtained via the Link SDK


account_uuid String

An identifier for the specific account, can be obtained via the /accounts endpoint.


Returns

balance Float

The real time balance remaining within the account


currency_code String

ISO 4217 currency code representing the currency of the balance. A dataset of all countries and their associated codes can be found here.


account_uuid String

Identifier for the account, how you reference the account when making data calls.


account_name String

The name of the account within the financial instituition, for your convenience.


account_type String

Type of bank account (e.g. Checking, savings, credit, loan etc.)

View account types

ChargeCard

A credit line that must be paid off in full each month.


CreditCard

Bank issued credit card


CurrentAccount

A standard checking account


Loan

A Loan account


Mortgage

A Mortgage account


PrePaidCard

A prepaid debit card


Savings

A standard savings account

Was this section helpful? 

Endpoint

POST https://sandbox.leantech.me/v1/balance

bash

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

JSON

// Example response
{
"balance": 15035.85,
"currency_code": "SAR",
"account_uuid": "01bb8b3f-8462-470b-b2ed-14eb15b95fa2",
"account_name": "Mockbank1 Checkings Account",
"account_type": "Checkings"
}

Transactions

Required permissions: transactions

The /transactions endpoint allows you to retrieve an end user's transactions data held by the financial institution.

Request

entity_uuid String

The identifier for your user’s bank entity. This is obtained via the Link SDK


account_uuid String

An identifier for the specific account, can be obtained via the /accounts endpoint.


Returns

Returns an array of transactions with the following attributes.

description String

A description of transaction.


amount Float

Value of the transaction. Negative numbers indicate a purchase, positive indicates income.


currency_code String

ISO 4217 currency code representing the currency of the balance. A dataset of all countries and their associated codes can be found here.


category String

A categorisation for the transaction.


type String

The type of transaction, i.e. Card Purchase


pending Bool

A boolean indicator showing whether the transaction has been completed or not.


timestamp String

A UTC timestamp for the time the transaction was made.


Was this section helpful? 

endpoint

POST https://sandbox.leantech.me/v1/transactions

bash

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

json

// Example response
[
{
"description": "Al Ghunaim Stationery",
"amount": -43.0,
"currency_code": "SAR",
"category": "Education",
"type": "Card Purchase",
"pending": false,
"timestamp": "2020-03-12T10:32:12Z"
}, {
"description": "Leanbank ATM Deposit",
"amount": 650.0,
"currency_code": "SAR",
"category": "ATM",
"type": "Cash Transfer",
"pending": false,
"timestamp": "2020-03-12T02:44:13Z"
}, {
"description": "Assaraya Turkish Restaurant",
"amount": -74.0,
"currency_code": "SAR",
"category": "Restaurant",
"type": "Card Purchase",
"pending": false,
"timestamp": "2020-03-10T08:01:35Z"
}, {
"description": "McDonalds - Sultanah, Riyadh",
"amount": -22.0,
"currency_code": "SAR",
"category": "Restaurant",
"type": "Contactless",
"pending": false,
"timestamp": "2020-03-08T11:02:41Z"
}, {
"description": "LuLu Hypermarket, Murabba",
"amount": -289.96,
"currency_code": "SAR",
"category": "Groceries",
"type": "Card Purchase",
"pending": false,
"timestamp": "2020-03-02T05:44:02Z"
}
]

Sending and recieving metadata

Sometimes you may want to send information in a request that is specific to your application, and have it returned when you make or retrieve requests about the object you've created.

Example: Getting back the related user_id in your system when querying accounts.

To do this, you can include a meta object in the body of any of your requests and Lean will store that against the object and return it when we send back any information relating to that object within a meta object in the body of the payload.

Was this section helpful? 

bash

# Example request
curl -X POST 'https://sandbox.leantech.me/v1/balance' \
--header 'Content-Type: application/json' \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \
--data-raw '{
"entity_uuid": "f08fb010-878f-407a-9ac2-a7840fb56185",
"account_uuid": "01bb8b3f-8462-470b-b2ed-14eb15b95fa2"
"meta": {
"user_id": "1234"
}
}'

json

// Example response
{
"balance": 15035.85,
"currency_code": "SAR",
"account_uuid": "01bb8b3f-8462-470b-b2ed-14eb15b95fa2",
"account_name": "Mockbank1 Checkings Account",
"account_type": "Checkings"
"meta": {
"user_id": "1234"
}
}