Data API Reference

In order to make calls to the Data API you will first need to install the LinkSDK into your application, please see the Link SDK guide for installation.

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? 

Application and Data Flow Infrastructure

Lean's Data API works both synchronously and asynchronously. Asynchronous calls allow you to request data that may take some time to complete without impacting your customer experience.

All requests to the Lean API must be made using Mutual Transport Layer Security (mTLS) to ensure encryption both ways.

An overview of the flow you will be implementing:

Was this section helpful? 


Synchronous Flow

By default, all requests to Lean data endpoints are made as synchronous calls. However, you do not need to use the asynchronous /results endpoint if you prefer to continue polling an endpoint until it's completed.

Timeouts

Some data requests take more than a minute to process. To prevent triggering timeouts on your server, Lean will return a response with a PENDING status after 50 seconds along with a results_id. In the background, Lean's system continues working on the request and will send a results.ready webhook to your webhook URL when the request has finished processing. At this point, you have three options:

  1. You can ignore the webhook and repeatedly make the same call until the initial request has been fully processed. When this happens, you will receive a response with an OK status and the requested payload or a FAILED status and the respective reason.

  2. You can wait for the results.ready webhook and make the same data call. This will not trigger Lean to start processing the data call from scratch and will instead return the results of the initial call you made.

  3. You can wait for the results.ready webhook and use the results_id from the intial data call's response to make a call to Lean's results endpoint to retrieve the data. This approach is similar to the Asynchronous flow detailed in the next section.

View sync statuses

OK

Request has completed, the data is available.


FAILED

Lean failed to access the requested data.


RECONNECT_REQUIRED

User input is required to reconnect the entity. Details here


PENDING

The request has timed out. You can continue to poll the endpoint until the results are ready or wait for the results.ready webhook to notify you.

Was this section helpful? 

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_id": "f08fb010-878f-407a-9ac2-a7840fb56185"
}'

json

// Example response on success
{
"status": "OK",
"payload": {
"full_name": "Joe Bloggs",
"mobile_number": "478 633 4345 0331",
"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-10-17T07:11:39.862804Z"
}

json

// Example response on timeout
{
"status": "PENDING",
"results_id": "e3421ba4-b241-4803-ac67-5eeb1dfd38dd",
"message": "Results not yet returned. Please try again later",
"timestamp": "2020-11-25T13:36:32.170912Z"
}

Asynchronous Flow

All requests can be made as asynchronous calls by adding "async": true into the body of your request.

When an asynchronous response is started, 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.

View Async Statuses

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.

Was this section helpful? 

endpoint

https://sandbox.leantech.me/v1/results/[RESULTS_ID]

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_id": "f08fb010-878f-407a-9ac2-a7840fb56185",
"async": true
}'

json

// 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"
}

json

// Webhook notification
{
"type": "results.ready",
"payload":
{
"id": "9b8ab652-cc95-4fb2-9340-59b0164c8fb2", // results_id
{
"message": "Your results are ready.",
"timestamp": "2021-01-08T18:05:19.244672Z"
}

bash

# Results request
curl -X GET 'https://sandbox.leantech.me/v1/results/6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4' \
--header 'Content-Type: application/json' \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \

json

// 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"
}

json

// Failure example
{
"status": "FAILED",
"results_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"message": "Internal error while processing request",
"timestamp": "2020-07-31T07:11:39.862804Z"
}

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"
}

Create a new Customer

A Customer object is a container for all the billing details for your customer and should map on a one-to-one basis with users in your platform. To create a Customer object, make a call to the Customer API endpoint with your application token in the header and the related user ID in your own database.

A new Customer object will be returned, and the customer_id should be saved in your own database.

Request

app_user_id String

The user ID in your own user table. This is to allow you to easily reconcile users and customers in the future.

Please note, this value has a unique constraint, no two Customers can share the same app_user_id

Response

app_user_id String

The user ID you assigned the customer during creation.


customer_id String

A UUID identifying the customer for future calls.


Full Customer API Reference

Was this section helpful? 

bash

curl -X POST 'https://api.leantech.me/customers/v1/' \
--header 'lean-app-token: YOUR_APP_TOKEN' \
--data-raw '{
"app_user_id": "001"
}'

json

{
"app_user_id": "001",
"customer_id": "f08fb010-878f-407a-9ac2-a7840fb56185"
}

Linking a Bank Account

To start the Link connection process, call Lean.link() from anywhere that has access to the global Lean object in the browser see the LinkSDK setup section to see how to install the LinkSDK.

Lean.link() requires three parameters:

Request

app_token String

This is the token you got when you created your application


customer_id String

The customer_id for the user you're connecting


app_user_id String

How you refer to your user in your internal database

This will be depreciated in future versions of the Lean Data API


permissions Array

When you use our Data API to get data from your user’s bank account, you can access different categories of data held in your user’s bank account: Accounts, Identity, Balance, and Transactions. You might not need access to all of these so choose only the categories you need for your application.


bank_identifier String (optional)

The bank identifier you want your customer to add a payment source for - you can read more about skipping bank selection here.


sandbox Boolean

Boolean to indicate if you're testing on our Sandbox and so trying to connect to a mock bank with a mock user. You will receive an error if your application has not been approved to connect to live bank accounts but the sandbox value has been set to false.


Response

When a customer has successfully authorized your application with their bank entity, the Link SDK will trigger an entity.created webhook which will include the entity object within it's payload, with its id. The id of this payload will be the entity_id you will use with the Data API to reference your customer’s bank entity in each call.

It is important to note that an entity.created webhook will only be sent the first time the same end user (derived from the app_user_id) authorizes the same bank account.

Keep in mind, if your user has accounts with more than one bank, you will need to store multiple entity_id’s for that user — one for each bank.

Test Users & OTPs

Was this section helpful? 

javascript

// Initialise the SDK in your application
Lean.link({
app_token: "2c9a80897169b1dd01716a0339e30003",
customer_id: "gh1hb010-897b-467b-9ac2-a7840fb289832"
app_user_id: "01-1234-98765",
permissions: ["identity", "accounts"],
bank_identifier: "HSBC_UAE",
sandbox: "true",
});

json

// .link() returns a webhook
{
"type": "entity.created",
"message": "An entity object has been created.",
"payload": {
"id": "f08fb010-878f-407a-9ac2-a7840fb56185",
"app_user_id": "00001",
"permissions": ["transactions", "balance", "identity", "accounts"],
"bank_details": {
"name": "Lean Mockbank",
"identifier": "LEANMB1_SAU",
"logo": "https://cdn.leantech.me/img/banks/white-lean.png",
"main_color": "#1beb75",
"background_color": "#001E26"
}
},
"timestamp": "2020-10-10T17:19:00.059933Z"
}

Identity

Required Permissions: identity

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

Request

entity_id String

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


Response

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: YOUR_APP_TOKEN' \
--data-raw '{
"entity_id": "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_id String

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


Response

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

account_id 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.

View account types

CURRENT

A current account.


SAVINGS

A savings account.


CREDIT

A credit card account.


iban String

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


credit Object

Credit account details, only available on CREDIT accounts.

View properties

card_number_last_four Int

The last 4 digits of the credit card attached to the account.


limit int

The credit limit of the account. This is always a negative value in the currency of the account.


next_payment_due_date Date

A UTC date indicating when the next payment on the credit card is due.


next_payment_due_amount Int

The balance due on the account when the next payment is required.

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_id": "f08fb010-878f-407a-9ac2-a7840fb56185" }'

json

// Example response
{
"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
}
}
]
}
}

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_id String

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


account_id String

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


Response

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_id 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: YOUR_APP_TOKEN' \
--data-raw '{
"entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185",
"account_id": "01bb8b3f-8462-470b-b2ed-14eb15b95fa2"
}'

JSON

// Example response
{
"balance": 15035.85,
"currency_code": "SAR",
"account_id": "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_id String

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


account_id String

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


start_date String (optional)

A UTC date specifying the start date you want to pull transactions from.


end_date String (optional)

A UTC date specifying the end date you want to pull transactions from.


insights Bool (optional)

Specifies whether you want categorization data with your data, defaults to false.


Response

Returns an array of transactions with the following attributes.

id String

The ID for the transaction in UUID format.


description String

The raw description of the 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.


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.


insights Object

Categorization information from Lean's Insights service.

Insights Object Attributes

description_cleansed String

A cleansed version of the description provided in the main body of a transaction response.


category String

The category that the transaction fits into.

Available Categories
CategoryDescription
BANK_FEES_AND_CHARGESTransactions relating to bank fees & charges
CHARITYTransactions relating to charitable causes
EDUCATIONTransactions relating to education i.e. school, university courses
ENTERTAINMENTTransactions relating to entertainment i.e. cinema, Netflix.
GOVERNMENTTransactions relating to government i.e. taxes, fines.
GROCERIESTransactions relating to food shopping
HEALTH_AND_WELLBEINGTransactions relating to health i.e. prescriptions and wellbeing i.e. yoga
LOANS_AND_INVESTMENTSTransactions relating to loans and investments i.e. Dividends and Loan repayments.
RENT_AND_SERVICESTransactions relating to household utilities and rent.
RESTAURANTS_DININGTransactions relating to dining and takeaways
RETAILTransactions relating to shopping
SALARY_AND_REVENUETransactions relating to income sources
TRANSFERTransactions relating to direct transfers
TRANSPORTTransactions relating to domestic travel i.e. Metro, cabs
TRAVELTransactions relating to international travel i.e. hotels, flights.
OTHERTransactions which couldn't be accurately classified

category_confidence Float

A percentage confidence score for the category.


type String

The type of transaction i.e. Transfer, Card Payment etc.

Available Types
TypeDescription
ATMTransaction was made via an ATM
CARDTransaction was made with a card
CHEQUETransaction was made with a cheque
MEPAYTransaction was made using MePay
PAYPALTransaction was made using Paypal
TRANSFERTransaction was made using a bank transfer
WALLETTransaction was made with a wallet service
OTHERTransaction was made with another source

type_confidence Float

A percentage confidence score for the type.


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: 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
}'

json

// Example response
{
"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
}
},
{
"id": "1f72f549-ea3c-3459-a71a-5440393e2b62",
"description": "POS-PURCHASE CARD NO.4******1 10098959 14-03-2020 SUMO SUSHI & BENTO DUBAI AE",
"amount": 86127.89,
"currency_code": "AED",
"pending": false,
"timestamp": "2020-08-06T00:00:00Z",
"insights": {
"description_cleansed": "SUMO SUSHI BENTO DUBAI AE",
"category": "RESTAURANTS_DINING",
"category_confidence": 1,
"type": "CARD",
"type_confidence": 1
}
},
{
"id": "e0dbc14e-2377-3b25-b57b-af48622b939a",
"description": "AMERICAN UNIVERSITY IN THE EMIRA DUBAI ARE",
"amount": 53253.12,
"currency_code": "AED",
"pending": true,
"timestamp": "2020-05-18T00:00:00Z",
"insights": {
"description_cleansed": "AMERICAN UNIVERSITY IN THE EMIRA DUBAI ARE",
"category": "EDUCATION",
"category_confidence": 1,
"type": "TRANSFER",
"type_confidence": 1
}
},
{
"id": "0426f10f-6c64-3368-8180-e402446789d3",
"description": "SUBWAY GRU T3 GUARULHOS BRA",
"amount": 93309.63,
"currency_code": "AED",
"pending": false,
"timestamp": "2018-10-23T00:00:00Z",
"insights": {
"description_cleansed": "SUBWAY GRU GUARULHOS BRA",
"category": "RESTAURANTS_DINING",
"category_confidence": 1,
"type": "TRANSFER",
"type_confidence": 1
}
},
{
"id": "06801fd6-9bc4-340b-9367-de097deec5ec",
"description": "ABU DHABI TOURISM AUTHORI DUBAI ARE",
"amount": 22865.11,
"currency_code": "AED",
"pending": true,
"timestamp": "2019-11-17T00:00:00Z",
"insights": {
"description_cleansed": "ABU DHABI TOURISM AUTHORI DUBAI ARE",
"category": "TRAVEL",
"category_confidence": 0.71,
"type": "TRANSFER",
"type_confidence": 0.99
}
},
{
"id": "578b5f6c-f64e-3832-a86a-157a6a82682a",
"description": "TELEGRAPHIC TRF REF NUM:O***********0 FITBAR RESTAURANT /REF/Fitbar Arsalan",
"amount": 18369.47,
"currency_code": "AED",
"pending": true,
"timestamp": "2019-02-26T00:00:00Z",
"insights": {
"description_cleansed": "TELEGRAPHIC TRF REF NUM O FITBAR RESTAURANT REF FITBAR ARSALAN",
"category": "RESTAURANTS_DINING",
"category_confidence": 0.96,
"type": "TRANSFER",
"type_confidence": 1
}
},
{
"id": "e49cef5e-5770-3261-be7e-b03f58a87052",
"description": "SUBWAY FUJAIRAH ARE",
"amount": -44378.57,
"currency_code": "AED",
"pending": true,
"timestamp": "2020-07-13T00:00:00Z",
"insights": {
"description_cleansed": "SUBWAY FUJAIRAH ARE",
"category": "RESTAURANTS_DINING",
"category_confidence": 0.99,
"type": "TRANSFER",
"type_confidence": 1
}
},
{
"id": "00d8e574-5faf-38a5-8182-5d1faf81cffb",
"description": "UNIQLO KLCC KUALA LUMPUR MYS",
"amount": -25718.43,
"currency_code": "AED",
"pending": true,
"timestamp": "2018-07-09T00:00:00Z",
"insights": {
"description_cleansed": "UNIQLO KLCC KUALA LUMPUR MYS",
"category": "RETAIL",
"category_confidence": 1,
"type": "TRANSFER",
"type_confidence": 1
}
},
{
"id": "76965310-9436-38b8-ac87-671e0639854b",
"description": "POS-PURCHASE CARD NO.4*****************0 120907 12-02-2020 3.69-AED APPLE.COM/BILL ITUNES.COM:IE",
"amount": -85638.29,
"currency_code": "AED",
"pending": true,
"timestamp": "2020-12-15T00:00:00Z",
"insights": {
"description_cleansed": "APPLE COM BILL ITUNES COM IRELAND",
"category": "ENTERTAINMENT",
"category_confidence": 1,
"type": "CARD",
"type_confidence": 1
}
},
{
"id": "5192a3e5-b6f0-38d3-afba-d0040fd2b7cb",
"description": "POS-PURCHASE CARD NO.4*************6311 115772 28-11-2019 46.90-AED DELIVEROO DMCC DUBAI:AE",
"amount": 9165.18,
"currency_code": "AED",
"pending": false,
"timestamp": "2019-08-22T00:00:00Z",
"insights": {
"description_cleansed": "DELIVEROO DMCC DUBAI UNITED ARAB EMIRATES",
"category": "RESTAURANTS_DINING",
"category_confidence": 1,
"type": "CARD",
"type_confidence": 1
}
}
],
"type": "transactions"
},
"results_id": "a504a76a-2006-458d-a811-f5b320902e3e",
"message": "Data successfully retrieved",
"timestamp": "2021-02-08T13:01:06.880156Z"
}

Delete Entities

You can delete connected entities via the API with a simple DELETE request. This will remove the user's login information from Lean systems.

Request

Reason enum

Please always pass in the value USER_REQUESTED.

Response

A 200 OK response will be sent back.

bash

curl -X DELETE 'sandbox.leantech.me/customers/v1/{customer_id}/entities/{entity_id}' \
--header 'Content-Type: application/json' \
--header 'lean-app-token: YOUR_APP_TOKEN' \
--data-raw '{
"reason": "USER_REQUESTED"
}'

Reauthentication and One Time Passwords

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.

Test Users & OTPs
How to test reconnect

Was this section helpful? 

bash

# Initial data call
curl -X POST 'https://sandbox.leantech.me/data/v1/accounts' \
--header 'Content-Type: application/json' \
--header 'lean-app-token: 4028f6df76b9e6350176ccff97520017' \
--data-raw '{ "entity_id": "52dbcb60-f0ae-431c-b435-db319fa5a0ce" }'

json

// Response to data call when user input required
{
"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"
}

javascript

Lean.reconnect({
app_token: "2c9a80897169b1dd01716a0339e30003",
reconnect_id: "20afcfd3-7ee3-44b8-9d6e-bf74b259fb90",
sandbox: "true",
});

json

// 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"
}

json

// 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"
}

Sending and Receiving 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: YOUR_APP_TOKEN' \
--data-raw '{
"entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185",
"account_id": "01bb8b3f-8462-470b-b2ed-14eb15b95fa2"
"meta": {
"user_id": "1234"
}
}'

json

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