Account data requests

Learn about the different types of account data you can request with the Data API.

You can discover information about a user’s finances through their accounts. The Data API currently supports four account types:

  • TRANSACTION: A transaction account is a checking or current account.
  • SAVINGS: An account that accrues interest at an agreed rate and interval. These accounts can have restrictions upon the withdrawal of funds.
  • BUSINESS_TRANSACTION: A transaction account for a business.
  • BUSINESS_SAVINGS: A savings account for a business.

Through account data requests, you can fetch:

  • an overview of all the accounts owned by a particular user
  • identity information associated with a specific account, for example full name
  • the balance of a particular account
  • information about all the transactions made from and to that account, within particular dates

Get all accounts

You can get all user accounts and any associated data by making a GET /accounts call.

You need to enable the accounts scope in Console to make this request.

/accounts request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts

/accounts response example

If the request is successful, you receive a response like the following.

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

/accounts response fields

FieldTypeDescriptionRequired
account_idstringUnique identifier of the account.:white-check-mark:
account_typestringThe account type.

The possible account types are TRANSACTION, SAVINGS, BUSINESS_TRANSACTION and BUSINESS_SAVINGS.
:white-check-mark:
account_number.ibanstringISO 13616-1:2007 international bank number.
account_number.numberstringBank account number.Only returned for AU and UK accounts.
account_number.sort_codestringUnited Kingdom SORT code.Only returned for UK accounts.
account_number.swift_bicstringISO 9362:2009 Business Identifier Codes:white-check-mark:
account_number.bsbstringBSB (Bank State Branch) number of the account.Only returned for AU accounts.
currencystringISO 4217 alpha-3 currency code of the account.:white-check-mark:
display_namestringHuman-readable name of the account.:white-check-mark:
update_timestampdatetimeLast update time of the account information.:white-check-mark:
provider.display_namestringDisplay name for the provider.Deprecated
provider.logo_uristringURI for the provider logo.Deprecated
provider.provider_idstringUnique identifier for the provider.:white-check-mark:

Get identity information for a single account

You can make a request to /info to get your user’s identity information held by the provider. This information can include name, address, emails, phone numbers, and the user's banking branch identifier.

You need to enable the info scope in Console to make this request.

When implementing this endpoint for UK accounts, the user's data should be requested within five minutes of the consent grant, and stored if necessary for your use case. Provider implementations of this endpoint differ due to varying interpretations of Article 10 of PSD2's Regulatory Technical Standards on Strong Customer Authentication. If the data becomes unavailable, we will return an sca_exceeded error message.

/info request

curl -H \"Authorization: Bearer ${access_token}\" \\\n  https://api.truelayer.com/data/v1/info

/info response example

{
    "results": [
        {
            "full_name": "John Doe",
            "update_timestamp": "2020-11-19T09:30:00Z"
        }
    ]
}

/info response fields

FieldTypeDescriptionAlways returned?
update_timestampdatetimeLast time the data has been updated from the provider.:white-check-mark:
full_namestringFull name of the user.:white-check-mark:
branch_idstringIdentifier of your user's banking branchOnly returned for some customers in France.
emails[...]array of stringsEmail addresses (if none are available, returns empty array)No
phones[...]array of stringsPhone numbers (if none are available, returns empty array)No

📘

Many providers only return the full_name in the response.

Get information for a specific account

You can get data associated with an account by making a GET /accounts/${account_id) call.

You need to enable the accounts scope in Console to make this request.

/accounts/{account_id} request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts/${account_id}

/accounts/{account_id} response example

{
  "results": [
    {
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "account_id": "f1234560abf9f57287637624def390871",
      "account_type": "TRANSACTION",
      "display_name": "Club Lloyds",
      "currency": "GBP",
      "account_number": {
        "iban": "GB35LOYD12345678901234",
        "number": "12345678",
        "sort_code": "12-34-56",
        "bsb": "067101"
      },
      "provider": {
        "provider_id": "lloyds"
      }
    }
  ]
}

/accounts/{account_id} response fields

FieldTypeDescriptionAlways returned?
currencystringISO 4217 alpha-3 currency code:white-check-mark:
availablenumberThe amount of funds available to the account holder. This takes into account any pending transactions and includes any overdraft facility.No
currentnumberThe amount of funds within the account. This does not include any pending transactions.:white-check-mark:
overdraftnumberPre-arranged overdraft limit. Available for all TRANSACTION and BUSINESS_TRANSACTION account types.No
update_timestampdatetimeLast update time.Only returned if applicable.

Get the balance of an account

You can make a GET request to /accounts/${account_id}/balance to get the balance in an account.

You need to enable the accounts and balance scopes in Console to make this request.

/accounts/${account_id}/balance request

curl -H "Authorization: Bearer ${access_token}" \   https://api.truelayer.com/data/v1/accounts/${account_id}/balance

/accounts/${account_id}/balance response example

For payments accounts (current and some savings), a negative balance amount represents funds owed to the provider from the account holder, such as an overdraft. A positive balance amount represents funds that are available to spend.

In the following response example, the account has a current balance of £1161.20, a £1000.00 overdraft facility. and has £11.60 spent in pending transactions. Therefore, available is calculated as 2150.80 = 1161.20 + 1000.00 - 11.60.

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

/accounts/${account_id}/balance response fields

FieldTypeDescriptionAlways returned?
currencystringISO 4217 alpha-3 currency code:white-check-mark:
availablenumberThe amount of funds available to the account holder. This takes into account any pending transactions and includes any overdraft facility.No
currentnumberThe amount of funds within the account. This does not include any pending transactions.:white-check-mark:
overdraftnumberPre-arranged overdraft limit. Available for all TRANSACTION and BUSINESS_TRANSACTION account types.No
update_timestampdatetimeLast update time.Only returned if applicable.

Get account transaction data

You can make a GET request to /accounts/${account_id}/transactions to get the transaction data for a specific account. Optionally, you can include from and to parameters to retrieve transaction data for a specified period of time.

For payment accounts (current and some savings), a positive transaction amount represents the addition of funds to the account, for example an incoming bank transfer. A negative transaction amount indicates the flow of funds out of an account, such as a shop purchase.

A negative running balance amount represents funds owed to the provider from the account holder, such as an overdraft. A positive running balance amount represents funds that are available to spend.

You need to enable the accounts and transactions scopes in Console to make this request.

/accounts/${account_id}/transactions request

curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/accounts/${account_id}/transactions?from=${from}&to=${to}"

/accounts/${account_id}/transactions response example

{
  "results": [
    {
      "transaction_id": "03c333979b729315545816aaa365c33f",
      "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.60,
        "currency": "GBP"
      },
      "meta": {
        "bank_transaction_id": "9882ks-00js",
        "provider_transaction_category": "DEB"
      }
    },
    {
      "transaction_id": "3484333edb2078e77cf2ed58f1dec11e",
      "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"
      }
    }
  ]
}

/accounts/${account_id}/transactions response fields

FieldTypeDescriptionAlways returned?
transaction_idstringUnique identifier of the transaction in a request. It may change between requests.:white-check-mark:
normalised_provider_transaction_idstringTrueLayer's recommended identifier of the transaction in a request. It will not change between requests.No
provider_transaction_idstringProvider's identifier of the transaction in a request. The format of this string will vary across providers.No
timestampdatetimeDate the transaction was posted on the account:white-check-mark:
descriptionstringOriginal description of the transaction as reported by the provider:white-check-mark:
transaction_typestringType of the transaction. transaction_type can have the following values:
  • CREDIT: Indicates an incoming fund
  • DEBIT: Indicates an outgoing fund
:white-check-mark:
transaction_categorystringCategory of the transaction:white-check-mark:
transaction_classificationarrayClassification of the transaction. Array can be empty if classification has not been successfully assigned.:white-check-mark:
merchant_namestringName of the merchantReturned if merchant has been identified.
amountnumberAmount of the transaction:white-check-mark:
currencystringISO 4217 alpha-3 currency code:white-check-mark:
metaobjectA collection of additional provider specific transaction metadata:white-check-mark:
running_balance.amountnumberIf available, contains the running balance.No
running_balance.currencystringIf available, contains the running balance currency - ISO 4217 alpha-3 currency codeNo