Asynchronous calls and 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.

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

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.

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

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

{
    "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 jittered exponential backoff. 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 -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/results/${task_id}