Get your user's account and card data

With the Data API, you can access data about both accounts and cards, such as account numbers, card numbers, or account holder information. Additionally, you can go deeper and access balance and transaction data at either the account or card level.

This section will help you configure Data API requests for both accounts and cards. It also contains examples, and explanations of, the data you get in responses from either API. Learn about using the Data API for:

• Accounts
• Cards

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

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

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

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

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_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_category": "DEB"
      }
    }
  ]
}

/accounts/${account_id}/transactions response fields

You can also use the Data API to get balance and transaction data associated with a user's card.

However, some providers do not support the cards scope. You can make a GET request to /providers to discover what data each provider supports by checking the scopes parameter provided in the response.

How far back you can request transactions from varies depending upon provider.

Get data for all cards

To get all stored user cards and associated data, make a GET request to /cards .

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

/cards request

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

/cards response example

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

/cards response fields

Note that the provider attributes display_name and logo_uri are deprecated. Details about the providers are available through the separate /providers endpoint.

Supported card networks

The card_network field can currently return the following results and supported networks.

Get data for a specific card

You can make a GET request to /cards/${account_id} to get data for a specific card.

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

/card/{account_id} request

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

/card/{account_id} response example

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

/card/{account_id}response fields

Note that the provider attributes display_name and logo_uri are deprecated. Details about providers are available through the separate /providers endpoint.

Get the balance on a card

Make a GET request to /cards/${account_id}/balance to get the balance on a user's card.

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

/cards/{account_id}/balance request

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

/cards/{account_id}/balance response example

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

/cards/{account_id}/balance response fields

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.

Get transaction data for a card

To get transaction data from a user's card, make a GET request to /cards/${account_id}/transactions .

You can include the optional from and to parameters to retrieve transaction data from a specified period of time.

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

/cards/{account_id}/transactions request

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

/cards/{account_id}/transactions response example

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

/cards/{account_id}/transactions response fields

You can optionally get a 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.