Data APIs

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.

ENDPOINTS

POST /data/v1/identity
POST /data/v1/accounts
POST /data/v1/balance
POST /data/v1/transactions
GET  /results/:results_id

Retrieve Identity

Parameters

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.

Response

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.

bash

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

json

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

Retrieve Accounts

Parameters

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.

Response

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, SAVINGSor 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.

View credit attributes

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.

bash

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

json

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

Retrieve balances

Parameters

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.

Response

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.

bash

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

json

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

Retrieve transactions

Parameters

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.

Response

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.

View Insights Attributes

description_cleansed string

A cleaned statement descriptor.

category string

The category that the transaction fits in to.

Category list

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.

View available Types

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.

bash

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

json

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

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

Reconnecting Accounts

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_REQUIREDalong 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.readyto 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_REQUIREDresponse. 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.

json

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

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

Using the Results endpoint

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.

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.

curl

# 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",
        "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 response
{
  "type": "results.ready",
  "payload": {
    "id": "9b8ab652-cc95-4fb2-9340-59b0164c8fb2"
  }
  "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"
}

Core Resources

APIs

Data APIs

ENDPOINTS

Retrieve Identity

Parameters

Response

bash

json

Retrieve Accounts

Parameters

Response

bash

json

Retrieve balances

Parameters

Response

bash

json

Retrieve transactions

Parameters

Response

bash

json

Reconnecting Accounts

json

javascript

json

json

Using the Results endpoint

curl

json

json

bash

json

json