An Entity is a representation of a Customer's bank connection. Entities can contain a single, or multiple accounts with a single financial institution. Entities are created when a customer links their account(s) with the LinkSDK and have permissioned access required to make identity, accounts, balances and transactions API calls.


GET /customers/v1/:customer_id/entities
GET /customers/v1/:customer_id/entities/:entity_id

The Entity object


id string

The unique entity identifier

customer_id string

The Customer object that owns the entity

bank_identifier string

The identifier signifies which bank the user's entity is linked with.

permissions object

Indicates which permissions have been granted by the user, this corresponds with the Data API calls you can make using the entity.


"id": "3bd4e44b-7cb9-3251-b205-c6fa6bac3244",
"customer_id": "497b457c-4a4b-42fb-b093-dbf9f303d63e",
"bank_identifier": "LEANMB1_SAU",
"permissions": {
"identity": true,
"accounts": true,
"balance": true,
"transactions": true

Create an Entity

Entities are created using the LinkSDK's .link() method.


app_token string

Your application token.

customer_id string

The Customer resource you want to connect an account for.

permissions array

An array of permissions you want to request consent for. The permissions requested here correspond to your ability to access the APIs associated with them.

bank_identifier string

Optional a Lean Bank identifier can be provided to skip the bank selection UI in the LinkSDK.

sandbox bool

Whether or not this connection is being generated in your sandbox or not.


The .link() method will generate a webhook of type entity.created when a bank is successfully connected.


app_token: YOUR_APP_TOKEN,
customer_id: "497b457c-4a4b-42fb-b093-dbf9f303d63e",
permissions: ["identity","accounts","balance","transactions"],
bank_identifier: "LEANMB1_SAU",
sandbox: true

Retrieve a list of Customer Entities

A GET request can be made to customers/v1/:customer_id/entities to retrieve a list of associated entities for that Customer.


curl -X GET 'https://sandbox.leantech.me/customers/v1/517f416f-6632-407f-9110-18e11a4fd4d2/entities' \
--header 'lean-app-token: YOUR_APP_TOKEN' \
--header 'Content-Type: application/json'

Retrieve a single Customer Entity

A GET request can be made to customers/v1/:customer_id/entities/:entity_id to retrieve a single Entity.


curl -X GET 'https://sandbox.leantech.me/customers/v1/517f416f-6632-407f-9110-18e11a4fd4d2/entities/3bd4e44b-7cb9-3251-b205-c6fa6bac3244' \
--header 'lean-app-token: YOUR_APP_TOKEN' \
--header 'Content-Type: application/json'

Delete an Entity

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


reason enum

Please always pass in the value USER_REQUESTED.


A 200 OK response will be sent back.


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"