---
updatedAt: 2026-07-16T13:23:25.000Z
agentTools:
  projectIndex: https://docs.truelayer.com/llms.txt
---

# Asynchronous calls and Data API webhooks

Simplify error and retry logic with asynchronous calls through webhooks.

You can make requests to Data API endpoints either synchronously or asynchronously. If you make asynchronous calls, the error and retry calls are made automatically.

You can make an asynchronous Data API call by passing a query parameter `async=true`. You'll get a response with a `results_uri` that will contain the results of your request once they are available. Our Data API supports asynchronous requests on all endpoints.

<Callout icon="📘" theme="info">
  ###

  We recommend using Data API asynchronously. Asynchronous access mitigates issues that are beyond the control of TrueLayer and removes the need for you to write your own error and retry logic as is it handled seamlessly.
</Callout>

After making an asynchronous API call, you can poll the `results_uri` and wait for completion. To avoid polling, you can pass a `webhook_uri` parameter to receive a real-time notification via `HTTP POST` (Webhook) when the request is completed.  Note that even if `webhook_uri` is passed the results will not be part of the `HTTP POST` payload but must be fetched at `results_uri`.

## Make asynchronous API calls

If a query parameter `async=true` is passed, the Data API immediately returns a response containing the  `results_uri`, `status` and `task_id`, which can be used to track the status of the call. When the results are ready, they will be available to fetch at the `results_uri`.

### Query parameters

| Query parameter | Type    | Description                                                           |
| --------------- | ------- | --------------------------------------------------------------------- |
| `async`         | boolean | If `true` the request is handled asynchronously                       |
| `webhook_uri`   | URI     | The URI where notification of completion will be sent via `HTTP POST` |

```curl Asynchronous &#x60;/accounts&#x60; request
curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/accounts/${account_id}?async=true&webhook_uri=${uri}"
```

The query will return one of the following `status` messages:

| Status        | Description                                           |
| ------------- | ----------------------------------------------------- |
| **Queued**    | The query is waiting to run                           |
| **Running**   | The query is currently running                        |
| **Succeeded** | The query has successfully returned results           |
| **Failed**    | The query is has failed to retrieve the query results |

```json Asynchronous &#x60;/accounts&#x60; response
{
    "results_uri": "https://api.truelayer.com/data/v1/results/b1bc9472-3c21-44ed-ade2-2e932c41ee64",
    "status": "Queued",
    "task_id": "b1bc9472-3c21-44ed-ade2-2e932c41ee64"
}
```

## Webhook callback payload

When an asynchronous request is completed, this payload will be sent to the `webhook_uri` via `HTTP POST`.

| Field               | Type     | Description                                                                    |
| ------------------- | -------- | ------------------------------------------------------------------------------ |
| `request_timestamp` | datetime | The time of the original request.                                              |
| `request_uri`       | string   | The URI of the original request.                                               |
| `credentials_id`    | string   | Unique string identifying a set of user credentials used to access a provider. |
| `task_id`           | string   | A unique ID associated with the task.                                          |
| `status`            | string   | **Succeeded** or **Failed**.                                                   |
| `results_uri`       | string   | The URI where results can be fetched from when available.                      |
| `error`             | string   | An error code.                                                                 |
| `error_description` | string   | Additional details about the error.                                            |

```json
{
    "request_timestamp" : "0001-01-01T00:00:00Z",
    "request_uri" : "https://api.truelayer.com/api/v1.0/accounts/1234/transactions?from=2017-01-01&to=2017-12-01",
    "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
    "task_id": "e1245d07-d846-42df-86d8-99b08b430a0",
    "status": "Succeeded | Failed",
    "results_uri": "https://api.truelayer.com/data/v1/results/e1245d07-d846-42df-86d8-99b08b430a0/",
    "error_description": "Error | null",
    "error": "Error | null"
}
```

## Webhook retry policy

We consider a webhook as having been successfully delivered when we receive a success status code (2xx) from the `webhook_uri`.

If we receive any other status code like **5xx** or **408** (for example, your API is temporarily unavailable), we will start retrying. Our retry policy is <a href="https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/" target="_blank">jittered exponential backoff</a>. We will immediately perform some fast retries and then start waiting increasingly longer. We will retry for a maximum of 6 times.

## Fetch the results

To fetch results from `results_uri` you will need to authenticate with a valid `access_token` corresponding to the `credentials_id` of the original request.

```curl
curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/results/${task_id}
```

<br />