NAV Navbar
Logo
curl

Introduction

Welcome to the TrueLayer API Reference!

TrueLayer allows financial applications to connect securely with their customer’s bank data. TrueLayer provides a unified interface between multiple financial institutions and third party applications over a common RESTful API.

Getting started

  1. Sign-up and obtain your client_id and client_secret. You will need to register at least one redirect_uri.
  2. Create an Authentication Link to authenticate your Customers
  3. Obtain an access_token following the Customer Authentication oAuth 2.0 flow
  4. Use the Data API to retrieve Customer’s personal information, account numbers and transaction data.

Access Methods

TrueLayer uses the following methods for access data from the providers:

Open Banking/PSD2: We use the Open Banking APIs for all available banks. We also use public proprietary APIs when available e.g. Monzo/Starling. The authentication is managed by the bank.

Credential-sharing: TrueLayer uses a proprietary technology in order to access private bank APIs when the public API is not available. The credentials are encrypted at rest and we don’t keep the encryption keys. Even if our Credentials Store is breached, the privacy of credentials will not be compromised. You can read more here.

Authentication

Customer authentication and Client authorization (to access financial data on their customer’s behalf) is achieved using the industry standard OAuth 2.0 three-legged server code flow RFC 6749

According to the OAuth roles TrueLayer is the Authorization Server, the Customer is the Resource owner and the Application is the Client.

Authentication

Definitions

Definition Description
Account A financial account with a Provider
Authorization Server The secure service hosted by TrueLayer that allows Customers to authenticate with their Provider credentials. It also offers API endpoints to obtain and renew access_token
Client An application implementing this API
Customer An application’s user and the owner of an account
Data API The API that provides access to Customers’s financial data
Permissions A set of permissions the Customer grant to the Client to access data on his behalf
Provider A supported bank or other financial institution
Credentials A set of identifiers and secrets the Customer uses to access his accounts with a Provider

Identifiers

Identifier name Description Confidentiality Lifetime
access_token A short-lived JWT token used to access data on behalf of the Customer Secret Credential sharing: 1 hour
Open Banking: provider-specific
client_id A unique string identifying a Client Public Forever
client_secret A secret key used to authenticate a Client Secret Forever (until rotated)
code A one time code that can be exchanged for an access_token Secret Single use
credentials_id Unique string identifying a set of Customer’s credentials used to access a Provider Public Forever
provider_id A unique string identifying a Provider Public Forever
redirect_uri A URI controlled by the Client where one time code is posted during authentication Public Forever
refresh_token A long lived code used to obtain a new access_token Secret Single use

Permissions

An Authentication Link must include a set of permissions in the scope parameter that your Client is requesting on behalf of the Customer. These permissions (or scopes) limit what endpoints the Client will be authorized to access in the Data API.

Scope Description API endpoint
info Allows access to Customer’s identity information held by the Provider /data/v1/info
accounts Allows access to Customer’s account numbers and details /data/v1/accounts, /data/v1/accounts/${account_id}
accounts + balance Allows access to Customer’s account balances /data/v1/accounts/${account_id}/balance
accounts + transactions Allows access to Customer’s account transactions /data/v1/accounts/${account_id}/transactions
cards Allows access to Customer’s card numbers and details /data/v1/cards, /data/v1/cards/${account_id}
cards + balance Allows access to Customer’s card balances /data/v1/cards/${account_id}/balance
cards + transactions Allows access to Customer’s card transactions /data/v1/cards/${account_id}/transactions
offline_access Allows access to Customer’s data after the short-lived access_token expires. When this permission is granted a refresh_token will be returned refresh_token

Customer Authentication

  1. Authentication Link: The customer’s browser is redirected to TrueLayer’s Authorization Server using a link that includes the application’s client_id, redirect_uri (already authorized for the Client) and a scope parameter defining the Permissions requested to the Customer. An arbitrary nonce is also required and an optional state argument can be included. You can build your Authentication Link in the console as shown below.

Auth Link Builder

  1. Customer log-in: The Customer selects his Provider and authenticates securely on the TrueLayer authorization server using his Provider credentials.

Choose your bank

  1. Code Redirect: Customer’s browser is redirected to the redirect_uri controlled by the Client with a code, the requested scope and the optional state

  2. Exchange code with access_token: The application exchanges the code received with a short-lived access_token (and optionally a refresh_token if the scope offline_access was requested) making a HTTP POST to the TrueLayer authorization server including the application client_id, client_secret and redirect_uri

  3. Access Data API: The application can use the obtained access_token to access data on behalf of the Customer. An Authorization header must be provided to access any endpoint of the Data API

  4. Renew the access_token: After the short-lived access_token expires (1 hour by default or provider specified) a new access_token can be obtained using the refresh_token

https://auth.truelayer.com/\
  ?response_type=code\
  &response_mode=form_post\
  &client_id=${client_id}\
  &redirect_uri=${redirect_uri}\
  &scope=${scope}\
  &nonce=${nonce}\
  &state=${state}

The first step in the authentication process is to redirect the Customer with a properly formatted link to TrueLayer Authorization Server. If the provider used for the authentication is already known, it can be supplied with an optional provider_id parameter, in order to skip the selection.

Parameters

Parameter Description
client_id Your client unique identifier
redirect_uri Must exactly match one of the registered redirect_uri for your Client
nonce A nonce is a random string, uniquely generated by the Client to allow the server to verify that a request has never been made before and helps prevent replay attacks.
state An opaque value used by the Client to maintain state between the request and callback.
scope Space-separated list of requested permissions. Please see Permissions
response_type MUST be: "code"
provider_id OPTIONAL. If supplied provider selection will be skipped.
response_mode OPTIONAL. if set to "form_post" the code will be submitted via form POST instead of a query string encoded redirect.
enable_mock OPTIONAL. if set to "true“ the authentication dialog will show a fictitious bank named "Mock" for testing. See Mock Users.
enable_open_banking_providers OPTIONAL. if set to "true” the authentication dialog will show all available Open Banking Providers.
enable_credentials_sharing_providers OPTIONAL. if set to "true“ the authentication dialog will show all available Credential-sharing Providers. If omitted, this is set to true by default.
enable_oauth_providers OPTIONAL. if set to "true” the authentication dialog will show all available oAuth Providers.

Mock users

These credentials can be used with the mock bank for testing normal behaviour and errors.

Username Password Behaviour
"john" "doe" Working normally with fake data.*
"error.account_permanently_locked" "error" Any endpoint will fail with account_permanently_locked
"error.account_temporarily_locked" "error" Any endpoint will fail with account_temporarily_locked
"error.internal_error" "error" Any endpoint will fail with internal_error
"error.provider_error" "error" Any endpoint will fail with provider_error
"error.user_input_required" "error" Any endpoint will fail with user_input_required
"error.wrong_credentials" "error" Any endpoint will fail with wrong_credentials

*Multiple user accounts can be tested with the following username/password combinations: john1/doe1, john2/doe2, up to john100/doe100.

Code Redirect

code=${code}&scope=${scope}&state=${state}

Customer’s browser is redirected to perform an HTTP GET (or HTTP POST in case response_mode has been set to "form_post") to the redirect_uri controlled by the Client with the following parameters:

Parameters

Parameter Description
code A one time code that can be exchanged with an access_token
state An opaque value used by the Client to maintain state between the request and callback.
scope Space-separated list of granted permissions. Please see Permissions
error If the user doesn’t grant the request scopes the redirect will contain an error parameter with value access_denied

Exchange code with access_token

curl -X POST \
    -d grant_type=authorization_code \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d redirect_uri=${redirect_uri} \
    -d code=${code} \
    https://auth.truelayer.com/connect/token
{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": "JTW-EXPIRY-TIME",
  "token_type": "Bearer",
  "refresh_token": "REFRESH-TOKEN-HERE"
}

After a code is obtained by the Client via redirect it can be exchanged for a short-lived access_token

Parameters

Parameter Description
client_id Your unique client identifier
client_secret Your client secret
code One time code obtained via the redirect
grant_type Must be: "authorization_code"
redirect_uri Must match the registered redirect_uri that was used to authorize access to the account.

Response

The Authorization server will respond with JSON

Parameter Description
access_token A short-lived JWT token used to access data on behalf of the Customer
expire_in access_token validity in seconds. Default is 1 hour or specified by provider.
refresh_token A long lived code use to obtain a new access_token when expired. It will be returned only if the scope offline_access was requested
token_type Must be: Bearer

Renew the access_token

curl -X POST \
    -d grant_type=refresh_token \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d refresh_token=${refresh_token} \
    https://auth.truelayer.com/connect/token
{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": "JTW-EXPIRY-TIME",
  "token_type": "Bearer",
  "refresh_token": "REFRESH-TOKEN-HERE"
}

After the short-lived access_token expires (1 hour by default) a new access_token can be requested using a refresh_token

Parameters

Parameter Description
grant_type Must be: "refresh_token"
client_id Your unique client identifier
client_secret Your client secret
refresh_token The refresh_token

Response

Parameter Description
access_token A short-lived JWT token used to access data on behalf of the Customer
expire_in access_token validity in seconds. Default is 1 hour
refresh_token A new refresh_token that must be used instead of the previous one
token_type Must be: Bearer

Delete encrypted credentials

This endpoint will revoke the access associated with the access token used for the request. In the case of credential-sharing, it will also purge the encrypted credentials.

DELETE /api/delete
Authorization: Bearer ${access_token}
curl -X DELETE -H "Authorization: Bearer ${access_token}" \
  https://auth.truelayer.com/api/delete

Submit access token for debug

This endpoint will return a debug_id that will allow TrueLayer to debug a particular issue. You can delete the credentials from the endpoint in two ways:

Remove the credentials completely using the delete endpoint found here or remove just the debug credentials using the /debug endpoint.

POST /api/debug
Content-Type: application/json

{"access_token": "ACCESS-TOKEN-HERE"}
curl -X POST -H "Content-Type: application/json" \
  -d '{"access_token": "ACCESS-TOKEN-HERE"}' https://auth.truelayer.com/api/debug
{
"credentials_id": "SSwF1CgQMLOs0qratFpybzF7uJ3hxwppiw1C4s+rT4I=",
"debug_id": "mock|U1N3RjFDZ1FNTE9zMHFyYXRGcHliekY3dUozaHh3cHBpdzFDNHMrYXk0ST0",
"provider_id": "mock"
}
DELETE /api/debug
Content-Type: application/json

{"access_token": "ACCESS-TOKEN-HERE"}
curl -X DELETE -H "Content-Type: application/json" \
  -d '{"access_token": "ACCESS-TOKEN-HERE"}' https://auth.truelayer.com/api/debug
{
    "credentials_id": "SSwF1CgQMLOs0qratFpybzF7uJ3hxwppiw1C4s+rT4I=",
    "debug_id": "mock|U1N3RjFDZ1FNTE9zMHFyYXRGcHliekY3dUozaHh3cHBpdzFDNHMrYXk0ST0",
    "provider_id": "mock"
}

Response

Parameter Description
credentials_id Unique TrueLayer credential ID
debug_id Computed TrueLayer key
provider_id Unique TrueLayer provider ID

List of supported providers

This endpoint returns the list of supported providers:

GET /api/providers
curl https://auth.truelayer.com/api/providers
{
        "display_name": "RBS Scotland",
        "logo_url": "https://auth.truelayer.com/img/banks/banks-icons/rbs-digital-icon.svg",
        "provider_id": "rbs-digital",
        "scopes": [
            "info",
            "accounts",
            "transactions",
            "balance",
            "cards",
            "offline_access"
        ]
    }

Response

Parameter Description
provider_id Unique TrueLayer provider ID
display_name Human friendly provider name
logo_url URL to the providers logo as used by TrueLayer
scopes List of Permissions supported by the provider

Data API v1

Data API provides endpoints to retrieve personal information, account numbers and transaction data. All endpoints require authorization using access_token.

Only one concurrent request per access token is allowed in the synchronous API, if a concurrent request is made a 409 request_conflict error is returned.

Data types

All of the responses returned by Data API are in JSON format. The description of the data types encoded in a JSON response is below.

Type Description
string A UTF-8 string
datetime An ISO8601 encoded date time
boolean true or false
number A float number

API response structure

All responses are JSON encoded.

Success

Field name Type Description
results array An array of objects

Success response

{
    "results": [
        {
            "hello": "world"
        }
    ]
}

Error

Field name Type Description
error string An error code for classification. eg: internal_error
error_description string When possible, extra details about the specific error
error_details object Additional key/value error details if available

Error response

{
    "error":  "internal_error",
    "error_description": "Well, this is embarrassing!",
    "error_details": {
        "detail_key": "detail value"
    }
}

Retrieve access_token metadata

GET /data/v1/me
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/me
{
    "results": [
        {
            "client_id": "test",
            "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
            "provider": {
                "display_name": "Lloyds Bank",
                "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
                "provider_id": "lloyds"
            },
            "scopes": [
                "info",
                "accounts",
                "balance",
                "transactions",
                "cards",
                "offline_access"
            ]
        }
    ]
}

Returns access_token metadata.

Response

Field Type Description
client_id string Your unique client identifier
credentials_id string Unique identifier of the set of credentials
provider.display_name string Display name for the Provider
provider.logo_uri string Uri for the Provider logo
provider.provider_id string Unique identifier for the Provider
scopes array Permission intersection for the Customer and Provider

Retrieve identity information

GET /data/v1/info
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/info
{
    "results": [
        {
            "addresses": [
                {
                    "address": "1 Market Street",
                    "city": "San Francisco",
                    "country": "US",
                    "zip": "94103"
                }
            ],
            "date_of_birth": "1984-07-03T00:00:00",
            "emails": [
                "john@doe.com"
            ],
            "full_name": "John Doe",
            "phones": [
                "+14151234567"
            ],
            "update_timestamp": "0001-01-01T00:00:00Z"
        }
    ]
}

Returns Customer’s identity information held by the Provider. This can include name, address, emails and phone numbers.

Response

Field Type Description
update_timestamp datetime last time the data has been updated from the provider
full_name string Full name of the Customer
date_of_birth datetime Date of birth of the Customer
addresses[...].address string Full address of the Customer
addresses[...].city string City
addresses[...].state string State
addresses[...].zip string Post code
addresses[...].country string ISO-3166-1 alpha-3 code of the country
emails[...] Array of strings Email addresses
phones[...] Array of strings Phone numbers

List all accounts

GET /data/v1/accounts
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts
{
  "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",
        "swift_bic": "LOYDGB2L"
      },
      "provider": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "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",
        "swift_bic": "LOYDGB2L"
      },
      "provider": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "provider_id": "lloyds"
      }
    }
  ]
}

Returns all Customer’s accounts and associated data

Response

Field Type Description
account_id string Unique identifier of the account
account_type string Type of the account
account_number.iban string ISO 13616-1:2007 international bank number
account_number.number string Bank account number
account_number.sort_code string United Kingdom SORT code
account_number.swift_bic string ISO 9362:2009 Business Identifier Codes
currency string ISO 4217 alpha-3 currency code of the account
display_name string Human readable name of the account
update_timestamp datetime Last update time of the account information
provider.display_name string Display name for the Provider
provider.logo_uri string Uri for the Provider logo
provider.provider_id string Unique identifier for the Provider

Account types

These account types are currently supported and can be returned as account_type

Type Description
TRANSACTION A transaction account is a checking account or current account
SAVINGS A savings account is an interest-bearing deposit account
BUSINESS_TRANSACTION A transaction account for a business
BUSINESS_SAVINGS A savings account for a business

Retrieve an account

GET: /data/v1/accounts/${account_id}
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts/${account_id}
{
  "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"
      }
    }
  ]
}

Returns data associated with the specified account_id

Response

Field Type Description
account_id string Unique identifier of the account
account_type string Type of the account[j]
account_number.iban string ISO 13616-1:2007 international bank number
account_number.number string Bank account number
account_number.sort_code string United Kingdom SORT code
account_number.swift_bic string ISO 9362:2009 Business Identifier Codes[k]
currency string ISO 4217 alpha-3 currency code of the account
display_name string Human readable name of the account
update_timestamp datime Last update time of the account

Account types

These account types are currently supported and can be returned as account_type

Type Description
TRANSACTION A transaction account is a checking account or current account
SAVINGS A savings account is an interest-bearing deposit account
BUSINESS_TRANSACTION A transaction account for a business
BUSINESS_SAVINGS A savings account for a business

Retrieve account balance

GET: /data/v1/accounts/${account_id}/balance
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts/${account_id}/balance
{
  "results": [
    {
      "currency": "GBP",
      "available": 1161.2,
      "current": 1161.2,
      "overdraft": 1000,
      "update_timestamp": "2017-02-07T17:33:30.001222Z"
    }
  ]
}

Returns balance information for the specified account_id

Response

Field Type Description
available number Available balance, including pre-arranged overdraft limit
currency string ISO 4217 alpha-3 currency code
current number Current balance
overdraft number Pre-arranged overdraft limit. Available for all “TRANSACTION” and “BUSINESS_TRANSACTION” account types. See Account Types
update_timestamp datetime Last update time

Retrieve account transactions

GET: /data/v1/accounts/${account_id}/transactions
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/accounts/${account_id}/transactions?from=${from}&to=${to}"
{
  "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",
      "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"
      }
    }
  ]
}

Returns transaction data for the specified account_id.

Parameters

Field Type Description
from datetime OPTIONAL. Returns transactions posted on or after this date. Default value is date as of the API request minus 3 months
to datetime OPTIONAL. Returns transactions up to and including this date. Default value is date as of the API request

Response:

Field Type Description
transaction_id string Unique identifier of the transaction
timestamp datetime Date the transaction was posted on the account
description string Original description of the transaction as reported by the Provider
transaction_type string Type of the transaction
transaction_category string Category of the transaction
transaction_classification array Classification of the transaction
merchant_name string Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object OPTIONAL. A collection of additional Provider specific transaction metadata

List all cards

GET /data/v1/cards
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards
{
  "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": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "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": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "provider_id": "lloyds"
      }
    }
  ]
}

Returns all Customer’s cards and associated data

Response

Field Type Description
account_id string Unique identifier of the account
card_network string Processing network (eg. VISA)
card_type string Type of card (eg. Credit)
currency string ISO 4217 alpha-3 currency code of the account
display_name string Human readable name of the account
partial_card_number string Last 4 digits of the card
name_on_card string If available, the name on the card
valid_from string If available, the valid from date
valid_to string If available, the valid to date
update_timestamp datetime Last update time of the card information
provider.display_name string Display name for the Provider
provider.logo_uri string Uri for the Provider logo
provider.provider_id string Unique identifier for the Provider

Retrieve a card

GET /data/v1/cards/${account_id}
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards/${account_id}
{
  "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"
    }
  ]
}

Returns a Customer’s card and associated data

Response

Field Type Description
account_id string Unique identifier of the account
card_network string Processing network (eg. VISA)
card_type string Type of card (eg. Credit)
currency string ISO 4217 alpha-3 currency code of the account
display_name string Human readable name of the account
partial_card_number string Last 4 digits of the card
name_on_card string If available, the name on the card
valid_from string If available, the valid from date
valid_to string If available, the valid to date
update_timestamp datetime Last update time of the card information

Retrieve card balance

GET: /data/v1/cards/${account_id}/balance
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards/${account_id}/balance
{
  "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"
    }
  ]
}

Returns card balance information for the specified account_id

Response

Field Type Description
available number Available balance
currency string ISO 4217 alpha-3 currency code
current number Current balance
credit_limit number Card credit limit
last_statement_balance number Card balance at time of last statment, if available
last_statement_date string Date of last statement, if available
payment_due number Minimum amount required by due date
payment_due_date number Date by which payment due should be remitted
update_timestamp datetime Last update time

Retrieve card transactions

GET: /data/v1/cards/${account_id}/transactions
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/cards/${account_id}/transactions?from=${from}&to=${to}"
{
  "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",
      "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"
      }
    }
  ]
}

Returns card transaction data for the specified account_id.

Parameters

Field Type Description
from datetime OPTIONAL. Returns transactions posted on or after from date. Default value is date as of the API request minus 3 months
to datetime OPTIONAL. Returns transactions up to and including this date. Default value is date as of the API request

Response

Field Type Description
transaction_id string Unique identifier of the transaction
timestamp datetime Date the transaction was posted on the card
description string Original description of the transaction as reported by the Provider
transaction_type string Type of the transaction
transaction_category string Category of the transaction
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata

Asynchronous Requests and Webhooks

Data API supports asynchronous requests on all endpoints. You can make an asynchronous API call by passing a query parameter async=true for any potentially long operation (For ex. fetching multiple years of transactions) and be returned with a results_uri that will contain the results of your request once they are available.

We recommend using Data API asynchronously. Asynchronous access mitigates issues that are beyond the control of TrueLayer and removes the need for you to write your own error and retry logic as is it handled seamlessly.

After making an asynchronous API call, you can poll the results_uri and wait for completion. To avoid polling, you can pass a webhook_uri parameter to receive a real-time notification via HTTP POST (Webhook) when the request is completed.

Please note that even if webhook_uri is passed the results will not be part of the HTTP POST payload but must be fetched at results_uri.

Make Asynchronous API calls

Request

GET: /data/v1/accounts/${account_id}/transactions
Header: "Authorization: Bearer ${access_token}"
curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/accounts/${account_id}?async=true&webhook_uri=${uri}"

Response

{
    "results_uri": "https://api.truelayer.com/data/v1/results/b1bc9472-3c21-44ed-ade2-2e932c41ee64", 
    "status": "Queued", 
    "task_id": "b1bc9472-3c21-44ed-ade2-2e932c41ee64"
}

If a query parameter async=true is passed, the Data API immediately returns a response containing the results_uri, status and task_id, which can be used to track the status of the call. When the results are ready, they will be available to fetch at the results_uri.

The query will return one of the following status messages:

Status Description
Queued The query is waiting to run
Running The query is currently running
Succeeded The query has successfully returned results
Failed The query is has failed to retrieve the query results

Parameters

Field Type Description
async boolean If true the request is handled asynchronoulsy
webhook_uri URI The URI where notification of completion will be sent via HTTP POST

Webhook Callback Payload

When an asynchronous request is completed, this payload will be sent to the webhook_uri via HTTP POST.

Webhook payload

{
    "request_timestamp" : "0001-01-01T00:00:00Z",
    "request_uri" : "https://api.truelayer.com/api/v1.0/accounts/1234/transactions?from=2017-01-01&to=2017-12-01",
    "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
    "task_id": "e1245d07-d846-42df-86d8-99b08b430a0",
    "task_status": "Succeeded | Failed",
    "results_uri": "https://api.truelayer.com/data/v1/results/e1245d07-d846-42df-86d8-99b08b430a0/",
    "error_description": "Error | null",
    "error": "Error | null"
}
Field Type Description
request_timestamp datetime The time of the original request
request_uri string The URI of the original request
credentials_id string Unique string identifying a set of Customer’s credentials used to access a Provider
task_id string A unique ID associated with the task
task_status string Succeded or Failed
results_uri string The URI where results can be fetched from when available.
error string An error code
error_description string Extra details about the error

Fetch the results

Request

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

To fetch results from results_uri you will need to authenticate with a valid access_token corresponding to the credentials_id of the original request.

Transaction Categories

Supported set of transaction categories used to identify the type of a transaction. Values are mapped from each providers proprietary category model into a core set that is consistent across all providers.

Returned as transaction_category for both account and card transactions.

Type Description
ATM Deposit or withdrawal of funds using an ATM (Automated Teller Machine)
BILL_PAYMENT Payment of a bill
CASH Cash deposited over the branch counter or using a Cash & Deposit Machines
CASHBACK An option retailers offer to withdraw cash while making a debit card purchase
CHEQUE A document ordering the payment of money from a bank account to another person or organization
CORRECTION Correction of a transaction error
CREDIT Funds added to your account
DIRECT_DEBIT An automatic withdrawal of funds initiated by a third party at regular intervals
DIVIDEND A payment to your account from shares you hold
FEE_CHARGE Fees or charges in relation to a transaction
INTEREST Credit or debit associated to interest earned or incurred
OTHER Miscellaneous credit or debit
PURCHASE A payment made with your debit or credit card
STANDING_ORDER A payment instructed by the account-holder to a third party at regular intervals
TRANSFER Transfer of money between accounts
DEBIT Funds taken out from your account, uncategorised by the bank
UNKNOWN No classification of transaction category known

Transaction Classification

Transaction classification returns detailed category information for account transactions.

Category Subcategory
Income Income
Paycheck
Investment
Returned Purchase
Bonus
Interest Income
Reimbursement
Rental Income
Uncategorised Cash & ATM
Check
Entertainment Arts
Music
Dating
Movies & DVDs
Newspaper & Magazines
Social Club
Sport
Games
Education Tuition
Student Loan
Books & Supplies
Shopping Pets
Groceries
General
Clothing
Home
Books
Electronics & Software
Hobbies
Sporting Goods
Personal Care Hair
Laundry
Beauty
Spa & Massage
Health & Fitness Dentist
Doctor
Eye care
Pharmacy
Gym
Pets
Sports
Food & Dining Catering
Coffee shops
Delivery
Fast Food
Restaurants
Bars
Gifts & Donations Gift
Charity
Investments Equities
Bonds
Bank products
Retirement
Annuities
Real-estate
Bills & Utilities Television
Home Phone
Internet
Mobile Phone
Utilities
Auto & Transport Auto insurance
Auto payment
Parking
Public Transport
Service & Auto Parts
Taxi
Gas & Fuel
Travel Air Travel
Hotel
Rental Car & Taxi
Vacation
Fees & Charges Service Fee
Late Fee
Finance Charge
ATM Fee
Bank Fee
Commissions
Business Services Advertising
Financial Services
Office Supplies
Printing
Shipping
Legal
Taxes Federal Tax
State Tax
Local Tax
Sales Tax
Property Tax
Gambling Betting
Lottery
Casino
Home Rent
Mortgage
Secured loans
Pension & Payments Pension payments
Life insurance
Buildings and contents insurance
Health insurance

Error codes

The following error codes can be returned with the associated HTTP status.

Data API Errors

HTTP Status Description Error Code
200 Success
400 The supplied parameters are not valid. validation_error
400 Invalid date range provided. invalid_date_range
401 The credentials entered are incorrect. wrong_credentials
403 The account is temporarily locked by the provider. account_temporarily_locked
403 The account is permanently locked by the provider. account_permanently_locked
403 Access to the account has been revoked or expired. access_denied
403 User input is required by the provider. user_input_required
404 The requested account cannot be found. account_not_found
409 This request is already running. Please try again later. request_conflict
410 The selected provider recognises the user within a different context wrong_bank
500 Internal server error internal_server_error
501 Feature not supported by the provider endpoint_not_supported
503 The provider service is unavailable provider_error

Auth (OAuth2) API Errors

HTTP Status Description Error
200 Success
400 The request is missing a required parameter invalid_request
400 The client is not authorized to request an authorization token unauthorized_client
400 Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method) invalid_client
400 The resource owner or authorization server denied the request access_denied
400 The authorization server does not support obtaining an authorization code using this method unsupported_response_type
400 The requested scope is invalid, unknown, or malformed invalid_scope
400 The server encountered an unexpected condition that prevented it from fulfilling the request server_error
400 The authorization server is currently unable to handle the request due to a temporary overloading or maintenance temporarily_unavailable
400 The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client invalid_grant
400 The authorization grant type is not supported by the authorization server unsupported_grant_type