Entities

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.

ENDPOINTS

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

The Entity object

Attributes

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.


json

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

Parameters

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.


Response

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

javascript

Lean.link({
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.

bash

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.

bash

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.

Parameters

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