Access data in batch

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

Submit a POST request to the endpoint specifying access token and transaction time period.
Wait for a webhook notifying you that the job is complete.
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:

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

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

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

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer <ACCESS_TOKEN>`

The following fields can be included in the request body:

Field	Required	Example	Description
`from`	Yes	`2019-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.
`to`	Yes	`2019-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_uri`	No	`https://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.
`pending`	No	`true`	If 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.
`balance`	No	`true`	If set, the balance will also be returned for each account and/or card.
`account_ids_whitelist`	No	`["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:

Field	Type	Description
`results_uri`	`string`	The URI where results can be fetched from when available.
`status`	`string`	The request outcome. If successful, `Queued`.
`task_id`	`string`	A 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:

Field	Type	Description
`request_timestamp`	`datetime`	The ISO8601 encoded datetime specified in the original request
`request_uri`	`string`	The URI of the original request
`credentials_id`	`string`	Unique string identifying a set of End user’s 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 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

Header	Value
`Authorization`	Bearer <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:

Field	Type	Description
`results`	`BatchResult`	A `BatchResult` object.
`request`	`BatchRequest`	An object containing the parameters used for the request.
`task_id`	`string`	A unique ID associated with the task.
`status`	`string`	The request outcome. If successful, `Succeeded`.

BatchRequest has the following structure:

Field	Type	Description
`from`	`datetime`	The ISO8601 encoded date time passed as `from` query parameter in the original batch endpoint request.
`to`	`datetime`	The ISO8601 encoded date time passed as `to` query parameter in the original batch endpoint request.

BatchResult has the following structure:

Field	Type	Description
`cards`	`Asset` list	A list of `Asset` objects, one for each card associated to the credential set the token belongs to.
`accounts`	`Asset` list	A list of `Asset` objects, one for each account associated to the credential set the token belongs to.

Asset has the following structure:

Field	Type	Description
`account_id`	`string`	A unique ID associated with the card or the account (the same that would be returned if using `/cards` or `/accounts`)
`transactions`	`object` list	The list of transactions associated with the account or card for the specified time window.
`pending_transactions`	`object` list	The list of the pending transactions associated with the account or card (if there are no pending transactions this field will contain an empty list).
`balance`	`object` object	The 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

Header	Value
`Authorization`	`Bearer <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:

Field	Type	Description
`status`	`string`	Status of the batch request (`Failed`)
`error_details_list`	`ErrorDetails` list	A list of `ErrorDetails` containing details on the failure reason for each failed sub_task

ErrorDetails has the following structure:

Field	Type	Description
`sub_task_id`	`string`	Id of the failed sub task
`status_code`	`int`	Failure status code of the sub task
`error`	`string`	Failure error code of the sub task. One of: `bad_request`, `internal_server_error`, `unauthorized`, `not_found`, `forbidden`
`error_description`	`string`	Failure error description of the sub task
`sub_task_type`	`string`	Type 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"
        }
    ]
}