The Data APIs are a collection of endpoints to retrieve information from an Entity
object. The APIs you can access are dependent on the Permissions available for the Entity.
POST /data/v1/identityPOST /data/v1/accountsPOST /data/v1/balancePOST /data/v1/transactionsGET /results/:results_id
entity_id string
The Entity you want to fetch identity for.
async bool
Whether you want to receive the results asynchronously through the Results
endpoint.
full_name string
The full legal name of the account holder.
mobile_number string
The registered mobile number of the account holder.
gender string
The registered sex of the account holder.
national_identity_number string
The registered identity number of the account holder.
birth_date string
The birth date of the account holder.
email_address string
The registered email address of the account holder.
address string
The registered address of the account holder.
curl -X POST 'https://sandbox.leantech.me/data/v1/identity' \--header 'lean-app-token: YOUR_APP_TOKEN' \--header 'Content-Type: application/json'--data-raw '{"entity_id": "3bd4e44b-7cb9-3251-b205-c6fa6bac3244","async": false}'
{"status": "OK","payload": {"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"}}
entity_id string
The Entity you want to fetch identity for.
async bool
Whether you want to receive the results asynchronously through the Results
endpoint.
status string
The status of the request.
accounts array
An array of accounts associated with the Entity.
account_id string
The unique identifier for the account.
name string
The product name of the account.
currency_code string
The currency that the account stores value in.
type enum
Indicates the type of account. Can be CURRENT
, SAVINGS
or CREDIT
.
iban string
The IBAN for the account.
account_number string
The account number for the account.
credit object
The details of the credit agreements in place for the account.
card_number_last_four Int
The last 4 digits of the credit card number.
limit float
The maximum amount of credit allowed on the card. Please note, this value will always be a negative number.
next_payment_due_date Date
The UTC date that the next payment is due.
next_payment_due_amount Date
The amount due for the next payment. This indicates the balance on the entire statement, not the minimum payment.
curl -X POST 'https://sandbox.leantech.me/data/v1/accounts' \--header 'lean-app-token: YOUR_APP_TOKEN' \--header 'Content-Type: application/json'--data-raw '{"entity_id": "3bd4e44b-7cb9-3251-b205-c6fa6bac3244","async": false}'
{"status": "OK","payload": {"accounts": [{"account_id": "56a5e1a0-66db-4cbf-a76b-57f5db397aa2","name": "Destiny Current Account","currency_code": "AED","type": "CURRENT","iban": "SA000000522223152841","account_number": "522223152841","credit": null}, {"account_id": "e13ee58b-01bd-4867-8bd7-f0ed37ce0ce9","name": "Diamond Credit Card","currency_code": "AED","type": "CREDIT","iban": null,"account_number": null,"credit": {"card_number_last_four": 1232,"limit": -400000,"next_payment_due_date": "2022-05-14","next_payment_due_amount": 1773.21}}]}}
entity_id string
The Entity that holds the account you want to query.
account_id string
The individual account you want to fetch balances for. Retrieved from the /accounts
endpoint.
async bool
Whether you want to receive the results asynchronously through the Results
endpoint.
status string
The status of the request.
balance float
The amount stored in the account (please note, this will be a negative number if querying a CREDIT type account)
currency_code string
The ISO 3 letter currency code for the currency the account stores balance in.
account_id string
The unique identifier for the account.
account_name string
The friendly name for the account.
account_type string
Indicates the type of account, can be CURRENT
, SAVINGS
or CREDIT
type string
The type of API call you've made, will always be balance
results_id string
The ID for this result, this is used when retrieving results from the /results
endpoint.
curl -X POST 'https://sandbox.leantech.me/data/v1/balance' \--header 'lean-app-token: YOUR_APP_TOKEN' \--header 'Content-Type: application/json'--data-raw '{"entity_id": "3bd4e44b-7cb9-3251-b205-c6fa6bac3244","account_id": "e13ee58b-01bd-4867-8bd7-f0ed37ce0ce9","async": false}'
{"status": "OK","payload": {"balance": 15035.85,"currency_code": "SAR","account_id": "7b62eba3-4562-48ab-9911-5a3df1541c86","account_name": "mbu1 checkings account","account_type": "CURRENT","type": "balance"},"results_id": "f3f5b156-de64-42e8-bb8d-b187f4f7f96f","message": "Data successfully retrieved","timestamp": "2021-07-22T17:18:11.133496Z"}
entity_id string
The Entity that holds the account you want to query.
account_id string
The individual account you want to fetch transactions for. Retrieved from the /accounts
endpoint.
start_date string (optional)
A UTC date string specifying the start date you want to pull transactions from.
end_date string (optional)
A UTC date string specifying the end date you want to pull transactions from.
insights bool (optional)
When set to true
an insights object will be returned for each transaction indicating the category of the transaction and giving a cleansed description.
async bool (optional)
Whether you want to receive the results asynchronously through the Results
endpoint. Defaults to false.
status string
The status of the request.
transactions array
An array of transaction objects.
id string
The unique identifier for the transaction.
description string
The statement description for the transaction.
amount float
The amount paid / received for the transaction.
currency_code string
The currency that the transaction was performed with.
index int
Indicates the order of the transactions. Each date's first transaction will have an index of 0.
pending bool
Indicates whether the transaction has been finalised by the bank.
timestamp datetime
The UTC datetime the transaction was completed. Please note: this date is supplied in UTC, and some banks do not supply a time.
insights object
Not present if insights true
is not supplied in your call.
description_cleansed string
A cleaned statement descriptor.
category string
The category that the transaction fits in to.
Category | Description |
---|---|
BANK_FEES_AND_CHARGES | Transactions relating to bank fees & charges |
CHARITY | Transactions relating to charitable causes |
EDUCATION | Transactions relating to education i.e. school, university courses |
ENTERTAINMENT | Transactions relating to entertainment i.e. cinema, Netflix. |
GOVERNMENT | Transactions relating to government i.e. taxes, fines. |
GROCERIES | Transactions relating to food shopping |
HEALTH_AND_WELLBEING | Transactions relating to health i.e. prescriptions and wellbeing i.e. yoga |
LOANS_AND_INVESTMENT | Transactions relating to loans and investments i.e. Dividends and Loan repayments. |
RENT_AND_SERVICES | Transactions relating to household utilities and rent. |
RESTAURANTS_DINING | Transactions relating to dining and takeaways |
RETAIL | Transactions relating to shopping |
SALARY_AND_REVENUE | Transactions relating to income sources |
TRANSFER | Transactions relating to direct transfers |
TRANSPORT | Transactions relating to domestic travel i.e. Metro, cabs |
TRAVEL | Transactions relating to international travel i.e. hotels, flights. |
OTHER | Transactions which couldn't be accurately classified |
category_confidence float
A percentage confidence score from our category models with 1 being equal to 100% confidence.
type string
The payment method of the transaction, for example a card payment or bank transfer.
Type | Description |
---|---|
ATM | Transaction was made via an ATM |
CARD | Transaction was made with a card |
CHEQUE | Transaction was made with a cheque |
MEPAY | Transaction was made using MePay |
PAYPAL | Transaction was made using Paypal |
TRANSFER | Transaction was made using a bank transfer |
WALLET | Transaction was made with a wallet service |
OTHER | Transaction was made with another source |
type_confidence float
A percentage confidence score from our type models with 1 being equal to 100% confidence.
type string
The type of API call you've made, will always be transactions
.
results_id string
The ID for this result, this is used when retrieving results from the /results
endpoint.
curl -X POST 'https://sandbox.leantech.me/data/v1/transactions' \--header 'lean-app-token: YOUR_APP_TOKEN' \--header 'Content-Type: application/json'--data-raw '{"entity_id": "3bd4e44b-7cb9-3251-b205-c6fa6bac3244","account_id": "e13ee58b-01bd-4867-8bd7-f0ed37ce0ce9""insights": true,"async": false}'
{"status": "OK","payload": {"transactions": [{"id": "5f28efc2-8ff3-4137-85a5-a3779e57845a","description": "CARREFOUR DUBAI AR","amount": -100.000,"currency_code": "SAR","index": 0,"pending": false,"timestamp": "2020-04-06T00:00:00Z","insights": {"description_cleansed": "CARREFOUR","category": "GROCERIES","category_confidence": 0.88,"type": "TRANSFER","type_confidence": 0.98}},{"id": "c182b8d3-68d5-44a4-b7ce-58debd5ce1dc","description": "NETFLIX.COM Amsterdam NL","amount": -26.000,"currency_code": "SAR","index": 13,"pending": false,"timestamp": "2020-04-06T00:00:00Z","insights": {"description_cleansed": "NETFLIX","category": "ENTERTAINMENT","category_confidence": 1,"type": "TRANSFER","type_confidence": 0.98}}],"type": "transactions"},"results_id": "655ec6e5-f7a6-4802-8d58-3c57327d1b1a","message": "Data successfully retrieved","timestamp": "2021-07-22T17:29:10.194997Z"}
When you make a call to our data API that requires user input before results can be retrieved our API will respond with a status of RECONNECT_REQUIRED
along with a reconnect_id
and a results_id
. This is required in scenarios like when the user's bank requires an OTP on each login, or when a bank requires us to renew the authentication with a user periodically.
You can submit the reconnect_id
to the LinkSDK reconnect() function on your front-end to prompt the user to submit the required input at a time of your choosing.
Example: If you run a CRON job every night to refresh balances, some banks may require an OTP but your customer could be asleep. In this case you can record the reconnect_id and send a push notification in the morning when they are more likely to reauthenticate.
Once the user has succesfully submitted the required input, we will send two webhooks one with status entity.reconnected
and one with results.ready
to notify you that the results of your original call are ready to be collected. We will include the results_id
that was part of the initial RECONNECT_REQUIRED
response. You can use this results_id
to collect the results from the results endpoint or you can make make data requests to the reconnected entity.
// Example response to a Data call{"status": "RECONNECT_REQUIRED","payload": {"reconnect_id": "20afcfd3-7ee3-44b8-9d6e-bf74b259fb90","type": "reconnect"},"results_id": "fae0ff1b-b0b7-481d-9c0a-533e0abfc798","message": "User input is required to reconnect with the bank","timestamp": "2020-12-30T16:40:49.779695Z"}
Lean.reconnect({app_token: "2c9a80897169b1dd01716a0339e30003",reconnect_id: "20afcfd3-7ee3-44b8-9d6e-bf74b259fb90",sandbox: "true",});
// Webhook received after successful reconnect{"type": "entity.reconnected","payload": {"id": "a2533394-6fcb-4407-989d-c35e96f34aa3" // the entity_id"reconnect_id": "6222a07e-3aa8-42ba-87df-0ef989f36d19"}"message": "The entity was successfully reconnected.","timestamp": "2021-01-08T18:05:19.244672Z"}
// Webhook to retrieve original data call{"type": "results.ready","payload": {"id": "9b8ab652-cc95-4fb2-9340-59b0164c8fb2", // results_id}"message": "Your results are ready.","timestamp": "2021-01-08T18:05:19.244672Z"}
When an asynchronous response is started or if a call to the Data API times out, a call to Lean’s API will respond with a results_id
and a status of PENDING
.
From this point, you can continue to poll the /results
endpoint with your results_id
until the request has completed. Alternatively, when the request completes, Lean will send a webhook to your Webhook URL notifying you that the request has completed at which point you can then request the data from the /results
endpoint.
To retrieve your results from the /results
endpoint you simply need to send a GET
request to the results endpoint and append the results_id
returned in the original response. Like all requests to Lean's backend, remember to include your lean-app-token
in the header.
PENDING
- Request is still being processed by Lean.
OK
- Request has completed, the data is available. Please note: this does not mean the call itself was successful, this will be determined during data retrieval.
FAILED
- Lean failed to access the requested data. Please note: This means something went wrong processing the original request.
MFA_REQUIRED
- Not currently in use, will be used for future OTP entry flow.
# Example requestcurl -X POST 'https://sandbox.leantech.me/v1/identity' \--header 'Content-Type: application/json' \--header 'lean-app-token: YOUR_APP_TOKEN' \--data-raw '{"entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185","async": true}'
// Response{"status": "PENDING","results_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4","message": "Results not yet returned. Please try again later","timestamp": "2020-07-31T07:11:39.862804Z"}
// Webhook response{"type": "results.ready","payload": {"id": "9b8ab652-cc95-4fb2-9340-59b0164c8fb2"}"message": "Your results are ready.","timestamp": "2021-01-08T18:05:19.244672Z"}
# Results requestcurl -X GET 'https://sandbox.leantech.me/v1/results/6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4' \--header 'Content-Type: application/json' \--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \
// Success Example{"status": "OK","payload": {"full_name": "Joe Bloggs","mobile_number": "478 633 4345 XXXX","gender": "MALE","national_identity_number": "739388015666","birth_date": "1986-12-23","email_address": "joe_bloggs@leantech.me","address": "140 Tabernacle Street, Shoreditch, EC2A 4SD, London, UK","type": "identity"},"results_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4","message": "Data successfully retrieved","timestamp": "2020-07-31T07:11:39.862804Z"}
// Failure example{"status": "FAILED","results_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4","message": "Internal error while processing request","timestamp": "2020-07-31T07:11:39.862804Z"}