Accounts and cards

Learn how to get details, available balances, and transaction data from user bank accounts and cards.

With our Data API, you can get relevant information such as balance details and transactions from your user's bank accounts and cards.

Accounts

You can find information about a user's finances through their accounts. We currently support four account types:

  • TRANSACTION: A transaction account is a checking account or current account. It is an account commonly used for everyday transactions. Can earn little or no interest. Also, could be linked to a short term lending product (such as an overdraft).
  • SAVINGS: An account that accrues interest at an agreed rate and interval. Can have restrictions around withdrawal of funds.
  • BUSINESS_TRANSACTION: A transaction account for a business
  • BUSINESS_SAVINGS: A savings account for a business

Get all accounts

You can get all user accounts and any associated data by making a GET /accounts call. You'll need the accounts permission to make this request.

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

You'll find the following in the response:

FieldTypeDescriptionRequired
account_idstringUnique identifier of the account.:white-check-mark:
account_typestringType of the account.: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:
{
  "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"
      }
    }
  ]
}

Get identity information

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.

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.

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

You'll get a response like the following:

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

The response can include the following parameters:

FieldTypeDescriptionRequired
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)Returned for most customers in Australia
phones[...]array of stringsPhone numbers (if none are available, returns empty array)Returned for most customers in Australia

📘

Note

Many providers will only return the full_name in the response.

Get account information of a specific account

You can get data associated with an account by making a GET /accounts/${account_id) call. You'll need the accounts permission to make this request.

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

The response includes the following parameters:

FieldTypeDescriptionRequired
account_idstringUnique identifier of the account.:white-check-mark:
account_typestringType of the account:white-check-mark:
account_number.ibanstringISO 13616-1:2007 international bank numberThis field is not returned by internal savings accounts on credential sharing.
account_number.numberstringBank account numberOnly returned for AU and UK accounts.
account_number.sort_codestringUnited Kingdom SORT codeOnly returned for UK accounts.
account_number.swift_bicstringISO 9362:2009 Business Identifier Codes:white-check-mark:
account_number.routing_numberstringRouting transit numberOnly returned for US-based accounts.
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 updated 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:
{
  "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"
      }
    }
  ]
}

Get the balance in an account

You can get the balance in an account by making a GET /accounts/${account_id}/balance call. You need the balance permission to make this call:

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts/${account_id}/balance
FieldTypeDescriptionRequired
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.
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.
update_timestampdatetimeLast update time.Only returned if applicable.

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 code sample, 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"
    }
  ]
}

Get account transaction data

You can also get the transaction data for a specific account by making a GET /accounts/${account_id}/transactions call. You can optionally include from and to parameters to retrieve transaction data from a specified period of time.

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

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'll get a response including:

FieldTypeDescriptionRequired
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.
provider_transaction_idstringProvider's identifier of the transaction in a request. The format of this string will vary across providers.
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.
running_balance.currencystringIf available, contains the running balance currency - ISO 4217 alpha-3 currency code
{
  "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"
      }
    }
  ]
}

Cards

You can also use our Data API to get the balance and transaction data associated with a user's card. Note that some providers may not support the cards scope. Make a GET call to /providers to determine which data is available for each provider by checking out the scopes parameter provided in the response.

Get all cards

You can get all stored user cards and associated data by making a GET /cards call. You'll need to have the cards permission to make this request.

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

You'll receive a response with the following:

FieldTypeDescriptionRequired
account_idstringUnique identifier of the account.:white-check-mark:
card_networkstringProcessing network (for example, VISA).:white-check-mark:
card_typestringType of card (for example, Credit).:white-check-mark:
currencystringISO 4217 alpha-3 currency code of the account.:white-check-mark:
display_namestringHuman-readable name of the account.:white-check-mark:
partial_card_numberstringLast 4 digits of the card.:white-check-mark:
name_on_cardstringIf available, the name on the card.
valid_fromstringIf available, the valid from date.
valid_tostringIf available, the valid to date.
update_timestampdatetimeLast updated time of the card 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:

Note that provider attributes display_name and logo_uri are deprecated.

The details about the providers are available on a separate /providers endpoint.

Supported card networks

These card networks are currently supported and can be returned as card_network.

TypeDescription
AMEXProcessing network is American Express.
MASTERCARDProcessing network is Mastercard.
VISAProcessing network is VISA.
NOT_SUPPORTED_BY_GEOProcessing network is not supported in the geographical location.
NOT_SUPPORTED_BY_PROVIDERProcessing network is not supported by the provider.
{
  "results": [
    {
      "account_id": "f7b093437032c216d4350b7d442b9c5ccc0e9f19",
      "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"
      }
    },
    {
      "account_id": "ad86fb1c213245b6b6594895068973efca5f9367",
      "card_network": "MASTERCARD",
      "card_type": "CHARGE",
      "currency": "GBP",
      "display_name": "Club Charge Card",
      "partial_card_number": "0055",
      "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"
      }
    }
  ]
}

Get card information of a specific card

To get data for a specific card, make a GET /cards/${account_id} call:

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

You'll get a response with the following:

FieldTypeDescriptionRequired
account_idstringUnique identifier of the account.:white-check-mark:
card_networkstringProcessing network (for example, VISA).:white-check-mark:
card_typestringType of card (for example, Credit).:white-check-mark:
currencystringISO 4217 alpha-3 currency code of the account.:white-check-mark:
display_namestringHuman-readable name of the account:white-check-mark:
partial_card_numberstringLast 4 digits of the card.:white-check-mark:
name_on_cardstringIf available, the name on the card.
valid_fromstringIf available, the valid from date.
valid_tostringIf available, the valid to date.
update_timestampdatetimeLast update time of the card information.
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:

Note that provider attributes display_name and logo_uri are deprecated.

The details about the providers are available on a separate /providers endpoint.

{
  "results": [
    {
      "account_id": "f7b093437032c216d4350b7d442b9c5ccc0e9f19",
      "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"
      }
    }
  ]
}

Get balance on a card

To get the balance on a user's card, make a GET /cards/${account_id}/balance call. You'll need the card and balance permissions.

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

You'll get a response with the following:

FieldTypeDescriptionRequired
availablenumberThe amount available to the card holder. This takes into account any pending transactions and credit limit.
currencystringISO 4217 alpha-3 currency code.:white-check-mark:
currentnumberThe amount of expenditure on the card. This does not include any pending transactions.:white-check-mark:
credit_limitnumberCard credit limit.
last_statement_balancenumberCard balance at time of last statement, if available.
last_statement_datestringDate of last statement, if available.
payment_duenumberMinimum amount required by due date.
payment_due_datenumberDate by which payment due should be remitted.
update_timestampdatetimeLast update time:white-check-mark:

You can optionally get an available amount in the response which takes any pending transactions into account. A negative available amount means the card’s credit limit has been exceeded. A positive available amount represents the credit available to the cardholder.

{
  "results": [
    {
      "available": 3279.0,
      "currency": "GBP",
      "current": 20.0,
      "credit_limit": 3300,
      "last_statement_balance": 420.0,
      "last_statement_date": "2017-01-28",
      "payment_due": 5.0,
      "payment_due_date": "2017-02-24",
      "update_timestamp": "2017-02-247T17:29:24.740802Z"
    }
  ]
}

Get card transaction data

To get transaction data from a user's card, make a GET /cards/${account_id}/transactions. You can optionally include from and to parameters to retrieve transaction data from a specified period of time.

📘

Make sure to use the from and to parameters together. Using one of them changes the time period to a default value of 88 days.

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

You'll get a response including:

ParameterTypeDescription
transaction_idstringUnique identifier of the transaction in a request. It may change between requests.
timestampdatetimeDate the transaction was posted on the account.
descriptionstringOriginal description of the transaction as reported by the provider.
transaction_typestringType of the transaction.

Possible values:
CREDIT: Indicates an incoming fund.
DEBIT: Indicates an outgoing fund.
transaction_categorystringCategory of the transaction.
transaction_classificationarrayClassification of the transaction. Array can be empty if classification has not been successfully assigned.
amountnumberAmount of the transaction.

A positive transaction amount reflects the flow of funds out of a card, such as a purchase. A negative amount indicates the flow of funds into the card, for example a refund.
currencystringISO 4217 alpha-3 currency code.
metaobjectA collection of additional provider-specific transaction metadata.

You can optionally get an running_balance.amount in the response which displays any available running balance. A positive running balance amount represents money owed to the provider by the cardholder. A negative running balance amount represents money owed to the cardholder by the provider. For the complete list of optional and mandatory response parameters, see our API reference.

{
  "results": [
    {
      "transaction_id": "a15d8156569ba848d84c07c34d291bca",
      "timestamp": "2018-01-16T00:00:00+00:00",
      "amount": 24.25,
      "currency": "GBP",
      "description": "SAINSBURYS SMRKT STORE 128",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "running_balance": {
        "amount": 1238.60,
        "currency": "GBP"
      },
      "meta": {
        "cardNumber": "1234********5678",
        "location": "INTERNET"
      }
    },
    {
      "transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
      "timestamp": "2018-03-19T00: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"
      }
    }
  ]
}

Did this page help you?