Handling asynchronous responses

🚧
It's recommended to adapt the data workflow and avoid the usage of async flow.

Lean will fallback to an asynchronous workflow for a Data API call (like: accounts, transactions, identity, expenses... etc) in two cases:

When a synchronous Data API call is delayed for more than 50 seconds
When the parameter async is set to true for a specific Data API request

1. Handling Pending Responses for Synchronous Requests

When synchronously calling any of the Data APIs with async: false (which is the default value), Lean's system falls back to an Asynchronous flow if the response was delayed for more than 50 seconds.

So for all the data APIs, you have to handle a PENDING response as per the below:

Sync Request

curl -X POST 'https://sandbox.sa.leantech.me/data/v2/accounts?async=false&page=0&size=50&force_refresh=false&verbose=false' \
    --header 'Content-Type: application/json' \
    --header 'lean-app-token: YOUR_APP_TOKEN' \
    --data-raw '{ 
      "entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185"
    }'

Processing the request takes more than 50 seconds, so the request falls back to async

Pending Response

{
  "status": "PENDING",
  "results_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
  "message": "Results not yet returned. Please wait",
  "timestamp": "2020-07-31T07:11:39.862804Z"
}

Results Ready Webhook

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

Get Results API

You can now fetch your results with a GET request:

curl -X GET 'https://sandbox.sa.leantech.me/data/v2/results/6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4?page=0&size=50' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT'

2. Handling Pending Responses for Asynchronous Requests

When calling Lean's Data APIs Asynchronously (async: true), our response to your requests will have a status of PENDING and a results_idas follows:

Async Request

curl -X POST 'https://sandbox.sa.leantech.me/data/v2/accounts?async=true&page=0&size=50&force_refresh=false&verbose=false' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_JWT' \
    --data-raw '{ 
      "entity_id": "f08fb010-878f-407a-9ac2-a7840fb56185"
    }'

Pending Response

{
  "status": "PENDING",
  "results_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
  "message": "Results not yet returned. Please wait",
  "timestamp": "2020-07-31T07:11:39.862804Z"
}

Results Ready Webhook

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

Get Results API

You can now fetch your results with a GET request:

curl -X GET 'https://sandbox.sa.leantech.me/data/v2/results/6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4?page=0&size=50' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT'