Access data in batch

Get historical transactions and balances for all accounts and cards from a single provider.

📘

This feature is in public beta. You can use it in sandbox and production.

The batch endpoint reduces integration complexity by letting you retry historical transactions and balances for all accounts and cards for a single connection.

If a user chooses to link multiple cards or accounts from a single provider, you can access transaction, pending transaction and balance data for all these accounts in a single asynchronous call to the /batch/transactions endpoint.

To get data with the /batch/transactions endpoint:

  1. Submit a POST request to the endpoint specifying access token and transaction time period.
  2. Wait for a webhook notifying you that the job is complete.
  3. GET results from the results_uri specified in the webhook payload, using the access token.

Setup

# Get a valid access token and export it as an environment variable:
export ACCESS_TOKEN=your-access-token

# Set up a request bin on https://requestbin.com/ - you will use it to receive our webhook
# Put the request body in a JSON file, for example, `batch_request.json`:
echo '{
  "from": "2020-01-01",
  "to": "2020-07-01",
  "pending": true,
  "balance": true,
  "webhook_uri": "https://your-webhook-uri.com/"
}' > batch_request.json

Fetch data with the batch endpoint

To access data using the batch endpoint:

  1. Submit a POST request to batch endpoint specifying access token:
curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --request POST \
  --data @batch_request.json \
  https://api.truelayer.com/data/v1/batch/transactions

You'll get a response like the following:

{
    "results_uri": "https://api.truelayer.com/data/v1/batch/results/8e35198d-f488-4e7d-8f41-991c8ace45f2",
    "status": "Queued",
    "task_id": "8e35198d-f488-4e7d-8f41-991c8ace45f2"
}
  1. Wait for a webhook notifying you that the job is complete..
{
    "request_timestamp" : "0001-01-01T00:00:00Z",
    "request_uri" : "https://api.truelayer.com/",
    "results_uri": "https://api.truelayer.com/data/v1/results/e1245d07-d846-42df-86d8-99b08b430a0",
    "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
    "task_id": "e1245d07-d846-42df-86d8-99b08b430a0",
    "status": "succeeded"
}
  1. Obtain results from the results_uri specified in the webhook payload, using the access token.
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  https://api.truelayer.com/data/v1/results/e1245d07-d846-42df-86d8-99b08b430a0

You'll get the results in the response:

{
    "request": {
        "from": "2018-09-28T00:00:00",
        "to": "2020-11-19T11:40:26.481103"
    },
    "results": {
        "accounts": [{
            "account_id": "12b48043fa864c798484a9cdd7cf196a",
            "transactions": [{...}],
            "pending_transactions": [{...}],
            "balance": {...}
        }],
        "cards": [{
            "account_id": "9e56cad7d782649e768df41751532824",
            "transactions": [{...}],
            "pending_transactions": [{...}],
            "balance": {...}
        }]
    },
    "status": "Succeeded",
    "task_id": "8e35198d-f488-4e7d-8f41-991c8ace45f2"
}

Add a batch task to a task list

You can retrieve all card and account transactions with a single API call using our batch endpoint. Batch calls are asynchronous. In the response, you will find a results_uri where you can fetch the transactions once the batch task is complete.

If you specify a webhook_uri you will receive a webhook notification when the status of your task changes. Possible status values are Succeeded or Failed.

You can retrieve cards and accounts transactions once the task is complete using /batch/results.

• Request endpoint

POST /data/v1/batch/transactions

• Request headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer <ACCESS_TOKEN>

The following fields can be included in the request body:

FieldRequiredExampleDescription
fromYes2019-01-07 or
2019-01-07T10:00:00
An ISO8601 encoded date or datetime that specifies the lower limit of the time window you want to fetch transactions for.
toYes2019-05-07 or
2019-05-07T17:00:00
An ISO8601 encoded date or datetime that specifies the upper limit of the time window you want to fetch transactions for.
webhook_uriNohttps://app.api.example.com/The endpoint that will receive our notification webhook.
The webhook will be fired as a POST request - query parameters are allowed.
pendingNotrueIf set, also the pending transactions will be included in the response (if not specified it defaults to false ).
If the provider doesn’t support pending transactions, they won’t be included in the response.
balanceNotrueIf set, the balance will also be returned for each account and/or card.
account_ids_whitelistNo["32828340fa4c", "3100e17de12145"]A JSON array of account/card ids to be whitelisted - only accounts with the corresponding id’s will be returned in the batch response. When set in the request body at least one id must be provided. If a whitelisted account is not found, the batch call will fail.
# Put the request body in a JSON file, for example, `batch_request.json`:
echo '{
  "from": "2020-01-01",
  "to": "2020-07-01",
  "pending": true,
  "balance": true,
  "webhook_uri": "https://your-webhook-uri.com/"
}' > batch_request.json
curl -X POST -d @request.json \
  -H "Authorization: Bearer ${access_token}" \
  -H "Content-Type:application/json" \
  https://api.truelayer.com/data/v1/batch/transactions

You'll get a response with the following:

FieldTypeDescription
results_uristringThe URI where results can be fetched from when available.
statusstringThe request outcome. If successful, Queued.
task_idstringA unique ID associated with the task
{
    "results_uri": "https://api.truelayer.com/data/v1/batch/results/8e35198d-f488-4e7d-8f41-991c8ace45f2",
    "status": "Queued",
    "task_id": "8e35198d-f488-4e7d-8f41-991c8ace45f2"
}

Webhook notifications

When a batch task is completed, a payload will be sent to the webhook_uri specified in
the batch request via HTTP POST. The payload includes the following:

FieldTypeDescription
request_timestampdatetimeThe ISO8601 encoded datetime specified in the original request
request_uristringThe URI of the original request
credentials_idstringUnique string identifying a set of End user’s credentials used to access a provider
task_idstringA unique ID associated with the task
statusstringSucceeded or Failed
results_uristringThe URI that results can be fetched from when available.
{
    "request_timestamp" : "2020-11-19T09:30:00Z",
    "request_uri" : "https://api.truelayer.com/",
    "results_uri": "https://api.truelayer.com/data/v1/results/e1245d07-d846-42df-86d8-99b08b430a0",
    "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
    "task_id": "e1245d07-d846-42df-86d8-99b08b430a0",
    "status": "succeeded",
}

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

Retrieve batch results

Success case

If the batch job was successful, you can use the results_uri specified in the webhook payload to fetch your transactions.

• Request endpoint:

GET /data/v1/batch/results/<your-task-id>

• Request headers

HeaderValue
AuthorizationBearer <ACCESS_TOKEN>
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/batch/results/0cf3fca2-e64e-4a35-8280-7c5bd7b5dc43
Response

The schema of the response retrieved from results_uri has the following top-level structure:

FieldTypeDescription
resultsBatchResultA BatchResult object.
requestBatchRequestAn object containing the parameters used for the request.
task_idstringA unique ID associated with the task.
statusstringThe request outcome. If successful, Succeeded.

BatchRequest has the following structure:

FieldTypeDescription
fromdatetimeThe ISO8601 encoded date time passed as from query parameter in the original batch endpoint request.
todatetimeThe ISO8601 encoded date time passed as to query parameter in the original batch endpoint request.

BatchResult has the following structure:

FieldTypeDescription
cardsAsset listA list of Asset objects, one for each card associated to the credential set the token belongs to.
accountsAsset listA list of Asset objects, one for each account associated to the credential set the token belongs to.

Asset has the following structure:

FieldTypeDescription
account_idstringA unique ID associated with the card or the account (the same that would be returned if using /cards or /accounts)
transactionsobject listThe list of transactions associated with the account or card for the specified time window.
pending_transactionsobject listThe list of the pending transactions associated with the account or card (if there are no pending transactions this field will contain an empty list).
balanceobject objectThe account balance of the account or card.

Each element in the transactions array has the same schema of a transaction returned from /accounts/{account_id}/transactions or /cards/{account_id}/transactions .

Each element in the pending_transactions array has the same schema of a transaction returned from /accounts/{account_id}/transactions/pending or /cards/{account_id}/transactions/pending.

​​The returned balance​ has the same schema as a balance returned from /accounts/{account_id}/balance or /cards/{account_id}/balance​.

{
  "status": "Succeeded",
  "task_id": "0cf3fca2-e64e-4a35-8280-7c5bd7b5dc43",
  "request": {
    "from": "2019-05-10T00:00:00",
    "to": "2019-05-20T00:00:00"
  },
  "results": {
    "accounts": [
      {
        "account_id": "a467e5319ddc9ad99846465bd6f0127e",
        "transactions": [
          {
            "timestamp": "2019-05-10T00:00:00",
            "description": "EDF ENERGY",
            "transaction_type": "DEBIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Bills and Utilities",
              "Utilities"
            ],
            "merchant_name": "EDF ENERGY",
            "amount": -24.5,
            "currency": "GBP",
            "transaction_id": "1647dc2acf12438d8c348a379b85814a"
          },
          {
            "timestamp": "2019-05-20T00:00:00",
            "description": "REGENDA REDWING",
            "transaction_type": "DEBIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Investments",
              "Real-estate"
            ],
            "merchant_name": "REDWING LIVING",
            "amount": -150,
            "currency": "GBP",
            "transaction_id": "7cfc04c0f5c4c39a3e168b76ec607799"
          }
        ],
        "pending_transactions": [
          {
            "transaction_id": "a15d8156569ba848d84c07c34d291bca",
            "normalised_provider_transaction_id": "txn-a15d8156569ba848d",
            "provider_transaction_id": "33b5555724",
            "timestamp": "2019-05-20T00:00:00",
            "amount": 24.25,
            "currency": "GBP",
            "description": "SAINSBURYS SMRKT STORE 128",
            "transaction_type": "DEBIT",
            "transaction_category": "PURCHASE",
            "running_balance": {
              "amount": 1238.6,
              "currency": "GBP"
            },
            "meta": {
              "cardNumber": "1234********5678",
              "location": "INTERNET"
            }
          },
          {
            "transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
            "normalised_provider_transaction_id": "txn-af4d5470cc7ad6a83",
            "provider_transaction_id": "33b5555724",
            "timestamp": "2019-05-20T00:00:00",
            "amount": 46.82,
            "currency": "GBP",
            "description": "TALKTALK TELECOM",
            "transaction_type": "DEBIT",
            "transaction_category": "PURCHASE",
            "meta": {
              "provider_transaction_category": "DEB",
              "cardNumber": "1234********5678",
              "location": "INTERNET"
            }
          }
        ],
        "balance": {
​​            "currency": "GBP",
​​            "available": 200.12,
​​            "current": 200.12,
​​            "overdraft": 0,
​​            "update_timestamp": "2019-05-20T00:00:00"
​​        }
      },
      {
        "account_id": "9586f94c8b253dc83807171339ea5da9",
        "transactions": [
          {
            "timestamp": "2019-05-10T00:00:00",
            "description": "EDF ENERGY",
            "transaction_type": "DEBIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Bills and Utilities",
              "Utilities"
            ],
            "merchant_name": "EDF ENERGY",
            "amount": -24.5,
            "currency": "GBP",
            "transaction_id": "f80d0229693f61fcb6c1fb79f2c61af4"
          },
          {
            "timestamp": "2019-05-20T00:00:00",
            "description": "REGENDA REDWING",
            "transaction_type": "DEBIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Investments",
              "Real-estate"
            ],
            "merchant_name": "REDWING LIVING",
            "amount": -150,
            "currency": "GBP",
            "transaction_id": "bdf8979b2d9c80ad1db2053c2e18a483"
          }
        ],
        "pending_transactions": [],
        "balance": {
​​            "currency": "GBP",
​​            "available": 50.08,
​​            "current": 50.08,
​​            "overdraft": 0,
​​            "update_timestamp": "2019-05-20T00:00:00"
​​        }
      }
    ],
    "cards": [
      {
        "account_id": "8901414c1e40d6beb24dfe45f39f3912",
        "transactions": [
          {
            "timestamp": "2019-05-10T00:00:00",
            "description": "EDF ENERGY",
            "transaction_type": "CREDIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Bills and Utilities",
              "Utilities"
            ],
            "merchant_name": "EDF ENERGY",
            "amount": -24.5,
            "currency": "GBP",
            "transaction_id": "646a9145784840eb911fef6278fbc4e5"
          },
          {
            "timestamp": "2019-05-20T00:00:00",
            "description": "REGENDA REDWING",
            "transaction_type": "CREDIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Investments",
              "Real-estate"
            ],
            "merchant_name": "REDWING LIVING",
            "amount": -150,
            "currency": "GBP",
            "transaction_id": "27d48b9c7d943c285e870bceba5b033b"
          }
        ],
        "balance": {
​​            "available": 3279.0,
​​            "currency": "GBP",
​​            "current": 20.0,
​​            "credit_limit": 3300,
​​            "last_statement_balance": 420.0,
​​            "last_statement_date": "2019-04-30",
​​            "payment_due": 5.0,
​​            "payment_due_date": "2019-05-20",
​​            "update_timestamp": "2019-05-107T17:29:24.740802Z"
        }
      },
      {
        "account_id": "afb594831dacd544563b20be7c362a51",
        "transactions": [
          {
            "timestamp": "2019-05-10T00:00:00",
            "description": "EDF ENERGY",
            "transaction_type": "CREDIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Bills and Utilities",
              "Utilities"
            ],
            "merchant_name": "EDF ENERGY",
            "amount": -24.5,
            "currency": "GBP",
            "transaction_id": "cc96f312d45f2c96d9464e69873d6a04"
          },
          {
            "timestamp": "2019-05-20T00:00:00",
            "description": "REGENDA REDWING",
            "transaction_type": "CREDIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Investments",
              "Real-estate"
            ],
            "merchant_name": "REDWING LIVING",
            "amount": -150,
            "currency": "GBP",
            "transaction_id": "da5c341e2b790bb3bcfd0235829df37c"
          }
        ],
        "balance": {
​​            "available": 510.0,
​​            "currency": "GBP",
​​            "current": 200.0,
​​            "credit_limit": 710,
​​            "last_statement_balance": 420.0,
​​            "last_statement_date": "2019-04-30",
​​            "payment_due": 10.0,
​​            "payment_due_date": "2019-05-20",
​​            "update_timestamp": "2019-05-107T17:29:24.740802Z"
        }
      }
    ]
  }
}

Failure case

If the batch task was unsuccessful, you can use the results_uri specified in the webhook payload
to retrieve useful information on what went wrong.

• Request endpoint

GET /data/v1/batch/results/<your-task-id>

• Request headers

HeaderValue
AuthorizationBearer <ACCESS_TOKEN>
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/batch/results/0cf3fca2-e64e-4a35-8280-7c5bd7b5dc43

The response contains the details of each failed sub_task.

You'll get a response with the following:

FieldTypeDescription
statusstringStatus of the batch request (Failed)
error_details_listErrorDetails listA list of ErrorDetails containing details on the failure reason for each failed sub_task

ErrorDetails has the following structure:

FieldTypeDescription
sub_task_idstringId of the failed sub task
status_codeintFailure status code of the sub task
errorstringFailure error code of the sub task. One of: bad_request, internal_server_error, unauthorized, not_found, forbidden
error_descriptionstringFailure error description of the sub task
sub_task_typestringType of the failed sub task. One of Cards, Accounts, AccountTransactions, CardTransactions, AccountPendingTransactions, CardPendingTransactions
{
    "status": "Failed",
    "error_details_list": [
        {
            "sub_task_id": "d734dbf4-92a8-4d15-96e2-25f3571139ed",
            "status_code": 404,
            "error": "not_found",
            "error_description": "Unable to find one or more whitelisted asset ids",
            "sub_task_type": "BatchRequest"
        }
    ]
}