Creating an entity (Data API)

Entity model

An Entity maps to a user's entire relationship with a specific bank. You will need to decide on the permissions you want to gain consent for from your customer during the linking process.

❗️

Identity permissions should not be used in the corporate product as the identity API is not supported for corporate accounts.

An example Entity object will look something like the following:

{
  "id": "f6dcc0ae-20c6-318c-bdba-49fb2ced41ce",
  "customer_id": "6bc2336a-6d74-4e59-a492-65313423a8f8",
  "bank_identifier": "ENBD_UAE",
  "permissions": {
    "identity": true,
    "accounts": true,
    "balance": true,
    "transactions": true,
    "identities": false,
    "standing_orders": false,
    "scheduled_payments": false,
    "direct_debits": false,
    "beneficiaries": false
  }
}

📘

In UAE, the only relevant permissions are identity (only for retail accounts), accounts, balance and transactions. The remainder permissions will always be set to false.

How to create the entity

Entities are created by first calling the Lean.connect() method in the LinkSDK in your front-end. In order to make a .connect() call you need to provide the permissions for the endpoints you want to make calls for, your app_token and a customer_id.

Please see https://docs.leantech.me/link-sdk for more details on integrating the Link SDK into your application and additional functionality.

<button onClick={connectAccount([customer_id])}>Connect Account</button>

<script>
function connectAccount = (customer_id) => {
    Lean.connect({
        app_token: "YOUR_APP_TOKEN",
        customer_id: customer_id,
        end_user_id: "", //only applicable for corporate bank accounts
        permissions: ["identity", "accounts", "balance", "transactions"],
        sandbox: "false",
    })
}
</script>

When a customer completes the LinkSDK - please note, no details are shared directly from the SDK to your front-end. A Success, Error or Cancelled message can be returned from the SDK via a callback (depending on the platform you're integrating with, this is handled differently) in the following format:

{
    status: "SUCCESS",
    method: "LINK",
    message: "Customer created entity successfully"
}

The details of your newly created entity will instead be sent via a webhook to your backend services. Your front-end should therefore handle the success by making a call to your backend to refresh the data.

Getting confirmation of entity creation

When a customer successfully links their bank with your application a webhook is sent back to your application:

{
    "type": "entity.created",
    "message": "An entity object has been created.",
    "payload": {
        "id": "f08fb010-878f-407a-9ac2-a7840fb56185",
        "customer_id": "6bc2336a-6d74-4e59-a492-65313423a8f",
        "permissions": ["transactions", "balance", "identity", "accounts"],
        "bank_details": {
          "name": "Lean Mock Bank",
          "identifier": "LEANMB2",
          "logo": "https://cdn.leantech.me/img/banks/white-lean.png",
          "main_color": "#1beb75",
          "background_color": "#001E26"
        }
    },
    "timestamp": "2020-10-10T17:19:00.059933Z"
}

The new Entity details can be found under payload in the received webhook. It is up to you which details from this webhook you decide to save to your database, but at the minimum we suggest you save the entity_id for future use. It's also worth noting that a user can have multiple connected Entities - one for each bank they have an account for.