Create an Entity

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.

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

Front-end

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

Backend

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": "Emirates NBD",
          "identifier": "ENBD_UAE",
          "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.

Once you have an entity_id you can now make calls to the /data/v1/identity/ and /data/v1/accounts/ endpoints.

Transactions Call & Response:

Handle reconnection OTPs

When making a call to accounts, balance, identity and transactions endpoints, user verification may be required before the request can be completed (for example, an OTP or updated user credentials may be required).

When this happens, a RECONNECT_REQUIRED response will be returned:

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

When this happens the reconnect_id should be passed to your front-end and initialised like so:

Lean.reconnect({
    app_token: "2c9a80897169b1dd01716a0339e30003",
    reconnect_id: "20afcfd3-7ee3-44b8-9d6e-bf74b259fb90",
    sandbox: "false"
});

Once the user has successfully reconnected their account, a webhook notifying you of successful reconnection will be sent, as well as a results.ready webhook allowing you to pick up the originally requested data.

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

{
  "type": "results.ready",
  "payload": {
    "id": "9b8ab652-cc95-4fb2-9340-59b0164c8fb2", // results_id
  }
  "message": "Your results are ready.",
  "timestamp": "2021-01-08T18:05:19.244672Z"
}

Handle Asynchronous requests

When dealing with large amounts of data resulting in a timeout, or when a request is asked for specifically to be asynchronous - Lean will fallback to an asynchronous workflow.

When this happens instead of returning a payload, our response to your request will have a status of PENDING and a results_id.

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

When the requirements of this request have been satisfied, a webhook will be sent to your system with a type of results.ready

{
  "type": "results.ready",
  "payload": {
    "id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4", // results_id
  }
  "message": "Your results are ready.",
  "timestamp": "2021-01-08T18:05:19.244672Z"
}

You can now fetch your results with a GET request:

curl -X GET 'https://sandbox.leantech.me/v1/results/6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4' \
  --header 'Content-Type: application/json' \
  --header 'lean-app-token: YOUR_APP_TOKEN' \