GithubSign up
lean logo

Introduction

Link is Lean's official SDK that leverages the capabilities of modern browsers and mobile clients, such as asynchronous communication, encryption at REST, transit and much more, while giving you an optimised, customisable, conversion optimised user journey for your users to connect their accounts.

Testing before setting up your backend?

Use our Link Connect service to test calls and responses to our Data API without authorizing with the Link SDK.

Link Connect Guide →

Link SDK

To integrate Lean's Link SDK you will first need to add the SDK to your frontend by importing it into your site.

Once the SDK has been imported, you can access Lean as a global variable in your application.

Initializing

To start the Link connection process, call Lean.init() from anywhere that has access to the global object in the browser.

Lean.init() requires three parameters.

Parameters

app_token String

This is the token you got when you created your application

permissions Array

The permissions you're asking your user for

app_user_id String

How you refer to your user in your internal database

Was this section helpful? 

html

// import the SDK into your application
<script src="https://cdn.leantech.me/link/sdk/web/0.5.0/Lean.min.js" />

javascript

// Initialise the SDK in your application
Lean.init({ 
    app_token: "2c9a80897169b1dd01716a0339e30003", 
    permissions: ["identity", "accounts"], 
    app_user_id: "01-1234-98765",
});

Getting an Identifier

When a customer has successfully authorized your application with their bank entity, the Link SDK will return an entity_uuid . You will use this with the Data and Payments APIs to reference your customer's bank entity in each call.

If your user has accounts with more than one bank, you will need to store multiple entity_uuid's for that user, one for each bank

The Link response will be posted to your callback url as follows:

Was this section helpful? 

json

{ 
    "status": { 
        "code": "200", 
        "message": "Success, here's everything you need to retrieve your user's information" 
    }, 
    "data": { 
        "entity": { 
            "entity_uuid": "f08fb010-878f-407a-9ac2-a7840fb56185", 
            "app_user_id": "123", 
            "permissions": [ 
                "transactions", "balance", "identity", "accounts" 
            ], 
            "bank_details": { 
                "logo_url": "https://www.leantech.me/mb1logo.png", 
                "bank_identifier": "LEANMB1", 
                "name": "Lean Mockbank 1", 
                "primary_color": "#183F3F" 
            } 
        } 
    }
}

Callback URL

Results from the Link SDK will be sent to your server via a POST request from Lean made to the Callback URL in the application settings.

Response

status Object

Enables you to track the status of your request.

View child attributes

code String

The HTTP response code of the request. 200 indicates a success, 401 indicates failure.

message String

A description of the status, enables more effective debugging

entity Object

Information about the new bank entity created.

View child attributes

entity_uuid String

The identifier you will use to reference your customer's bank entity when making API calls.

app_user_id String

For your convenience, we’ll also pass the id your application uses to reference your customer.

permissions Array

The permissions your customer granted you.

bank_details Object

Attributes related to the bank that the entity originates from.

View child attributes

name String

The name of the bank where your user's entity and accounts exist.

bank_identifier String

For use with the /bank endpoint, allows you to query data on the bank related to the entity.

logo_url String

A URL pointing to an image of the bank's logo.

primary_color String

The HEX value of the primary color the bank uses for display purposes.

Next Steps

Now that you have an entity_uuid you can make further API calls to the Data and Payments APIs

Data API Reference →

Was this section helpful? 

json

// Success Example
{ 
    "status": { 
        "code": "200", 
        "message": "Success, here's everything you need to retrieve your user's information" 
    }, 
    "data": { 
        "entity": { 
            "entity_uuid": "f08fb010-878f-407a-9ac2-a7840fb56185", 
            "app_user_id": "00001", 
            "permissions": [ "transactions", "balance", "identity", "accounts" ], 
            "bank_details": { 
                "name": "Lean Mockbank 1", 
                "bank_identifier": "LEANMB1", 
                "logo_url": "https://www.leantech.me/mb1logo.png", 
                "primary_color": "#183F3F" 
            } 
        } 
    }
}

json

// Failure Example
{ 
    "status": { 
        "code": "401", 
        "message": "The username or password submitted was incorrect" 
    }, 
    "data": null
}

Link Connect

Link Connect is only available in the Sandbox environment.

Link Connect allows you to work with mock data from two fake entities in the Lean Mockbank. It will provide you with an entity_uuid for each entity. We built this to enable you to test functionality in the Data and Payments APIs without having to set up the Link SDK. As soon as you want to work with live data, you will need to connect to user's bank accounts with the Link SDK to get the entity_uuid.

Request

Headers

lean_app_token String

How Lean identifies your application. You can find the app token in your Application dashboard.

Body

bank_id Int

The bank in which your user’s account is held. For the sandbox, this is always 1, refering to the Lean Mockbank.

app_user_id String

How your application refers to the user internally in your databases.

username String

The user’s username for the bank (You can choose between mockbank_user_1 and mockbank_user_2)

note in production you will not have access to this data.

password String

The user’s password for the bank (This will be same as the username in the sandbox)

note in production you will not have access to this data.

permissions String

The list of permissions your user is willing to give you for this connection

Returns

status Object

Enables you to track the status of your request.

View child attributes

code String

The HTTP response code of the request. 200 indicates a success, 401 indicates failure.

message String

A description of the status, enables more effective debugging

entity Object

Information about the new bank entity created.

View child attributes

entity_uuid String

The identifier you will use to reference your customer's bank entity when making API calls.

app_user_id String

For your convenience, we’ll also pass the id your application uses to reference your customer.

permissions Array

The permissions your customer granted you.

bank_details Object

Attributes related to the bank that the entity originates from.

View child attributes

name String

The name of the bank where your user's entity and accounts exist.

bank_identifier String

For use with the /bank endpoint, allows you to query data on the bank related to the entity.

logo_url String

A URL pointing to an image of the bank's logo.

primary_color String

The HEX value of the primary color the bank uses for display purposes.

Was this section helpful? 

bash

-- Example Request 
curl -X POST 'https://link.leantech.me/link/v1/connect' \ 
    --header 'Content-Type: application/json' \ 
    --header 'lean-app-token: 2c9a80897169b1dd01716a0339e30003' \ 
    --data-raw '{ 
        "bank_id": 1, 
        "app_user_id": "00001", 
        "username": "mockbank_user_1", 
        "password": "mockbank_user_1", 
        "permissions": [ "identity", "accounts", "balance", "transactions" ] 
    }'

json

// Example response
{ 
    "status": { 
        "code": "200", 
        "message": "Success, here's everything you need to retrieve your user's information" 
    }, 
    "data": { 
        "entity": { 
            "entity_uuid": "f08fb010-878f-407a-9ac2-a7840fb56185", 
            "app_user_id": "00001", 
            "permissions": ["transactions", "balance", "identity", "accounts"], 
            "bank_details": { 
                "name": "Lean Mockbank 1", 
                "bank_identifier": "LEANMB1", 
                "logo_url": "https://www.leantech.me/mb1logo.png", 
                "primary_color": "#183F3F" 
            } 
        } 
    }
}