Documentation
Asset librariesConsole

➡️ Batch endpoint migration guide

Suggest Edits

We've decommissioning will soon decommission the batch endpoint API, but you can use the same functionality by calling a few API endpoints in sequence. This guide will demonstrate how to do this and help you transition from batch endpoints.

This can be broken down into separate, asynchronous API calls. In this example, we request transaction and balance information about two bank accounts and a credit card. You can repeat these steps for as many accounts and/or cards as you want information about.

  1. Request information about all accounts

  2. Retrieve account results

  3. Request transactions and balance for account 1 between a specified from and to period

  4. Retrieve transactions and balance results for account 1

  5. Request transactions and balance for account 2 between a specified from and to period

  6. Retrieve transactions and balance results for account 2

  7. Request card information

  8. Retrieve card results

  9. Request transactions and balance for the card between a specified from and to period

  10. Retrieve transactions and balance results for the card

1. Request account information

Send an asynchronous request to the /accounts endpoint with your access token:

curl --request GET \
     --url 'https://api.truelayer.com/data/v1/accounts?async=true&webhook_uri=https%3A%2F%2Fyour-webhook-uri.com%2F' \
     --header 'accept: application/json' \
     --header "Authorization: Bearer ${ACCESS_TOKEN}"

Which results in the following response:

{
    "results_uri": "https://api.truelayer.com/data/v1/results/84e81a2a-856b-45b5-9383-1e9d4379d3cb",
    "status": "Queued",
    "task_id": "84e81a2a-856b-45b5-9383-1e9d4379d3cb"
}

When your data is ready, you receive a webhook to your specified webhook URI with the following payload:

{
    "request_timestamp" : "0001-01-01T00:00:00Z",
    "request_uri" : "https://api.truelayer.com/data/v1/accounts",
    "results_uri": "https://api.truelayer.com/data/v1/results/84e81a2a-856b-45b5-9383-1e9d4379d3cb",
    "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
    "task_id": "84e81a2a-856b-45b5-9383-1e9d4379d3cb",
    "status": "succeeded"
}

2. Retrieve account results

Call the /results endpoint using your results_uri to get the account information:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  https://api.truelayer.com/data/v1/results/84e81a2a-856b-45b5-9383-1e9d4379d3cb

This returns the response:

{
  "results": [
    {
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "account_id": "12b48043fa864c798484a9cdd7cf196a",
      "account_type": "TRANSACTION",
      "display_name": "Club Lloyds",
      "currency": "GBP",
      "account_number": {
        "iban": "GB35LOYD12345678901234",
        "number": "12345678",
        "sort_code": "12-34-56",
        "swift_bic": "LOYDGB2L"
      },
      "provider": {
        "provider_id": "lloyds"
      }
    },
    {
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "account_id": "e6f360f69e3746c5eefa47629b962240",
      "account_type": "SAVINGS",
      "display_name": "Club Lloyds",
      "currency": "GBP",
      "account_number": {
        "iban": "GB35LOYD12345678901235",
        "number": "12345679",
        "sort_code": "12-34-57",
        "swift_bic": "LOYDGB2L"
      },
      "provider": {
        "provider_id": "lloyds"
      }
    }
  ]
}

See synchronous requests to skip the webhook and /results endpoints and instead fetch account information directly in step 1.

3. Request transactions and balance for the first account

Send an asynchronous request to the /accounts/{account_id}/transactions endpoint with your access token and required date range:

curl --request GET \
     --url 'https://api.truelayer.com/data/v1/accounts/12b48043fa864c798484a9cdd7cf196a/transactions?to=2020-01-01&from=2020-07-01&async=true&webhook_uri=https%3A%2F%2Fyour-webhook-uri.com' \
     --header 'accept: application/json' \
     --header "Authorization: Bearer ${ACCESS_TOKEN}"

Send another asynchronous request to the /accounts/{account_id}/balance endpoint for the first account

curl --request GET \
     --url 'https://api.truelayer.com/data/v1/accounts/12b48043fa864c798484a9cdd7cf196a/balance?async=true&webhook_uri=https%3A%2F%2Fyour-webhook-uri.com' \
     --header 'accept: application/json' \
     --header "Authorization: Bearer ${ACCESS_TOKEN}"

Webhook steps remain the same across all asynchronous requests.

4. Retrieve transactions and balance results for the first account

Call the /results endpoint using your results_uri when receiving your webhooks for the account transactions and account balance, which should give the following responses respectively:

{
  "results": [
    {
      "transaction_id": "03c333979b729315545816aaa365c33f",
      "normalised_provider_transaction_id": "txn-ajdifh38fheu5hgue",
      "provider_transaction_id": "9882ks-00js",
      "timestamp": "2018-03-06T00:00:00",
      "description": "GOOGLE PLAY STORE",
      "amount": -2.99,
      "currency": "GBP",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "transaction_classification": [
        "Entertainment",
        "Games"
      ],
      "merchant_name": "Google play",
      "running_balance": {
        "amount": 1238.6,
        "currency": "GBP"
      },
      "meta": {
        "bank_transaction_id": "9882ks-00js",
        "provider_transaction_category": "DEB"
      }
    },
    {
      "transaction_id": "3484333edb2078e77cf2ed58f1dec11e",
      "normalised_provider_transaction_id": "txn-2jdh8whf8w9rh3udh",
      "provider_transaction_id": "33b5555724",
      "timestamp": "2018-02-18T00:00:00",
      "description": "PAYPAL EBAY",
      "amount": -25.25,
      "currency": "GBP",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "transaction_classification": [
        "Shopping",
        "General"
      ],
      "merchant_name": "Ebay",
      "meta": {
        "bank_transaction_id": "33b5555724",
        "provider_transaction_category": "DEB"
      }
    }
  ]
}

{
  "results": [
    {
      "currency": "GBP",
      "available": 2150.8,
      "current": 1161.2,
      "overdraft": 1000,
      "update_timestamp": "2017-02-07T17:33:30.001222Z"
    }
  ]
}

5. Request the transactions and balance for the second account

Repeat step 3 with the second account_id.

6. Retrieve transactions and balance results for the second account

Repeat step 4 with respective webhook results_uri for all remaining requests.

Repeat this for each account that you want information about.

7. Request card information

The process for fetching cards is similar to fetching the accounts above in Step 1. except using the /cards endpoint.

curl --request GET \
     --url 'https://api.truelayer.com/data/v1/cards?async=true&webhook_uri=https%3A%2F%2Fyour-webhook-uri.com%2F' \
     --header 'accept: application/json' \
     --header "Authorization: Bearer ${ACCESS_TOKEN}"

8. Retrieve card results

Call the /results endpoint using your webhook results_uri to receive the card information.

{
  "results": [
    {
      "account_id": "9e56cad7d782649e768df41751532824",
      "card_network": "VISA",
      "card_type": "CREDIT",
      "currency": "GBP",
      "display_name": "Club Credit Card",
      "partial_card_number": "0044",
      "name_on_card": "A. N. Other",
      "valid_from": "2017-01",
      "valid_to": "2018-01",
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "provider": {
        "provider_id": "lloyds"
      }
    }
  ]
}

See synchronous requests to skip the webhook and /results endpoints and instead fetch card information directly in step 7.

9. Request transactions and balance for the card

Make an asynchronous request to the /cards/{account_id}/transactions endpoint using the required parameters.

curl --request GET \
     --url 'https://api.truelayer.com/data/v1/cards/9e56cad7d782649e768df41751532824/transactions?to=2020-01-01&from=2020-07-01&async=true&webhook_uri=https%3A%2F%2Fyour-webhook-uri.com%2F' \
     --header 'accept: application/json' \
     --header "Authorization: Bearer ${ACCESS_TOKEN}"

Send another asynchronous request to the /cards/{account_id}/balance endpoint:

curl --request GET \
     --url 'https://api.truelayer.com/data/v1/cards/9e56cad7d782649e768df41751532824/balance?async=true&webhook_uri=https%3A%2F%2Fyour-webhook-uri.com%2F' \
     --header 'accept: application/json' \
     --header "Authorization: Bearer ${ACCESS_TOKEN}"

10. Retrieve transactions and balance results for the card

Finally, when you call the /results endpoint using your webhook's results_uri, you receive the card transactions and balance.

{
  "results": [
    {
      "transaction_id": "a15d8156569ba848d84c07c34d291bca",
      "normalised_provider_transaction_id": "txn-ajdifh38fheu5hgue",
      "provider_transaction_id": "9882ks-00js",
      "timestamp": "2018-01-16T00:00:00+00:00",
      "description": "SAINSBURYS SMRKT STORE 128",
      "amount": 24.25,
      "currency": "GBP",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "transaction_classification": [
        "Shopping",
        "Groceries"
      ],
      "merchant_name": "Sainsburys",
      "running_balance": {
        "amount": 1238.6,
        "currency": "GBP"
      },
      "meta": {
        "cardNumber": "1234********5678",
        "location": "INTERNET"
      }
    },
    {
      "transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
      "normalised_provider_transaction_id": "txn-2jdh8whf8w9rh3udh",
      "provider_transaction_id": "33b5555724",
      "timestamp": "2018-03-19T00:00:00",
      "description": "TALKTALK TELECOM",
      "amount": 46.82,
      "currency": "GBP",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "transaction_classification": [
        "Bills and Utilities",
        "Internet"
      ],
      "merchant_name": "Talktalk",
      "running_balance": {
        "amount": 1262.85,
        "currency": "GBP"
      },
      "meta": {
        "provider_transaction_category": "DEB",
        "cardNumber": "1234********5678",
        "location": "INTERNET"
      }
    }
  ]
}

{
  "results": [
    {
      "available": 3279,
      "currency": "GBP",
      "current": 20,
      "credit_limit": 3300,
      "last_statement_balance": 420,
      "last_statement_date": "2017-01-28",
      "payment_due": 5,
      "payment_due_date": "2017-02-24",
      "update_timestamp": "2017-02-247T17:29:24.740802Z"
    }
  ]
}

Repeat steps 9 and 10 for any other cards you want information about.

You now have all the data originally supplied by the batch endpoint.

📘

Synchronous requests

You can also use synchronous calls when fetching account and card information by omitting the async and webhook_uri parameters in your request.

This reduces complexity by skipping the webhook step and directly receiving the payloads from the requests as opposed to fetching from the /results endpoints.

This also means that you can send all subsequent transactions, pending transactions and balance requests from the same function.

Updated 5 months ago