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.

FieldTypeDescription
asyncbooleanIf true the request is handled asynchronously
webhook_uriURIThe 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:

StatusDescription
QueuedThe query is waiting to run
RunningThe query is currently running
SucceededThe query has successfully returned results
FailedThe 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.

FieldTypeDescription
request_timestampdatetimeThe time of the original request.
request_uristringThe URI of the original request.
credentials_idstringUnique string identifying a set of user credentials used to access a provider.
task_idstringA unique ID associated with the task.
statusstringSucceeded or Failed.
results_uristringThe URI where results can be fetched from when available.
errorstringAn error code.
error_descriptionstringAdditional 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}

Did this page help you?