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.

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:

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

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