Handling asynchronous responses

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.

❗️
Attention!
It's recommended to use the sync flow (async=false) for all requests by adapting the new data workflow

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

Sync Request

curl -X POST 'https://sandbox.leantech.me/data/v2/accounts?async=false' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_JWT' \
    --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": "fed7bac9-b039-4ae6-aef2-5eab54b97e50",
    "message": "Please wait for a webhook or try again later.",
    "meta": null,
    "timestamp": "2026-01-18T17:08:00.860657281Z",
    "status_detail": null,
    "data": null
}

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.leantech.me/data/v2/results/6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4' \
  --header 'Content-Type: application/json' \

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.leantech.me/data/v2/accounts?async=true' \
    --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": "fed7bac9-b039-4ae6-aef2-5eab54b97e50",
    "message": "Please wait for a webhook or try again later.",
    "meta": null,
    "timestamp": "2026-01-18T17:08:00.860657281Z",
    "status_detail": null,
    "data": null
}

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.leantech.me/data/v2/results/6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT'