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
  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.

Open API / Swagger 2.0

TrueLayer API follows the Open API standards and provides machine readable specifications.

Description URI
Swagger UI https://api.truelayer.com/swagger/ui
Swagger JSON https://api.truelayer.com/swagger/v1.0/swagger.json

URIs

API URI
Authorization Server https://auth.truelayer.com
Data API https://api.truelayer.com

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 1 hour
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
accounts Allows access to Customer’s account numbers and details /data/v1/accounts, /data/v1/accounts/${account_id}
balance Allows access to Customer’s account balances /data/v1/accounts/${account_id}/balance
info Allows access to Customer’s identity information held by the Provider. /data/v1/info
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
transactions Allows access to retrieve transactions data of Customer’s accounts. /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

Client Sign-up

In order to use TrueLayer API, you would need to create a developer account and obtain a client_id and a client_secret. You will also need to register at least one redirect_uri

Sign-up now!

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.

  2. 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 and will perform an HTTP POST 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) 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". Useful for testing purpose. Username "john" and password "doe" are a valid set of credentials.

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": 3600,
  "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 one of the registered redirect_uri

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
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": 3600,
  "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 purge all the encrypted credentials and grants associated with the access token used for the request.

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

Data API v1

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

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 response

{
    "error":  "internal_error",
    "error_description": "Well, this is embarrassing!"
}

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_id": "lloyds"
        }
    ]
}

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_id string Unique identifier of the 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 timestamp last time the data has been updated from the provider
full_name string Full name of the Customer
date_of_birth timestamp 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"
      }
    },
    {
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "account_id": "f1234560abf9f57287637624def390872",
      "account_type": "SAVING",
      "display_name": "Club Lloyds",
      "currency": "GBP",
      "account_number": {
        "iban": "GB35LOYD12345678901235",
        "number": "12345679",
        "sort_code": "12-34-57"
      }
    }
  ]
}

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 timestamp Last update time of the account information

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

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 timestamp 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

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,
      "update_timestamp": "2017-02-07T17:33:30.001222Z"
    }
  ]
}

Returns 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
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": [
    {
      "timestamp": "2017-02-01T00:00:00+00:00",
      "description": "INTEREST (GROSS)",
      "transaction_type": "CREDIT",
      "amount": 0.77,
      "currency": "GBP",
      "meta": {
        "bank_transaction_id": "039ccc24c3"
      }
    },
    {
      "timestamp": "2017-02-01T00:00:00+00:00",
      "description": "O/D USAGE FEE",
      "transaction_type": "DEBIT",
      "amount": -6,
      "currency": "GBP",
      "meta": {
        "transaction_type": "CHARGE",
        "bank_transaction_id": "c9bc0942f0"
      }
    },
    {
      "timestamp": "2017-01-30T00:00:00+00:00",
      "description": "THAMES WATER",
      "transaction_type": "DEBIT",
      "amount": -33.93,
      "currency": "GBP",
      "meta": {
        "transaction_type": "DIRECT_DEBIT",
        "bank_transaction_id": "33b5555724"
      }
    },
    {
      "timestamp": "2017-01-19T00:00:00+00:00",
      "description": "L B I COUNCIL TAX",
      "transaction_type": "DEBIT",
      "amount": -148,
      "currency": "GBP",
      "meta": {
        "transaction_type": "DIRECT_DEBIT",
        "bank_transaction_id": "23473ff316"
      }
    },
    {
      "timestamp": "2017-01-16T00:00:00+00:00",
      "description": "TV LICENCE MBP",
      "transaction_type": "DEBIT",
      "amount": -24.25,
      "currency": "GBP",
      "meta": {
        "transaction_type": "DIRECT_DEBIT",
        "bank_transaction_id": "08a7debb12"
      }
    },
    {
      "timestamp": "2017-01-03T00:00:00+00:00",
      "description": "ACME LIMITED",
      "transaction_type": "CREDIT",
      "amount": 12345.67,
      "currency": "GBP",
      "meta": {
        "transaction_type": "FASTER_PAYMENTS_INCOMING",
        "bank_transaction_id": "da188a719c"
      }
    }
  ]
}

Returns transaction data for the specified account_id.

Parameters

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

Response:

Field Type Description
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
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
balance.currency string ISO 4217 alpha-3 currency code
balance.available number Available balance
balance.current number Current balance
meta object 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"
    },
    {
      "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"
    }
  ]
}

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 timestamp Last update time of the card information

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 timestamp 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 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": [
    {
      "timestamp": "2017-01-16T00:00:00+00:00",
      "amount": 24.25,
      "currency": "GBP",
      "description": "PURCHASE DOMESTIC REFUND",
      "meta": {
          "cardNumber": "1234********5678",
          "location": "INTERNET",
          "store": "MARKS&SPENCER PLC"
      },
    },
    {
      "timestamp": "2017-01-17T00:00:00+00:00",
      "amount": -24.25,
      "currency": "GBP",
      "description": "PURCHASE DOMESTIC",
      "meta": {
          "cardNumber": "1234********5678",
          "location": "INTERNET",
          "store": "MARKS&SPENCER PLC"
      },
    }
  ]
}

Returns card transaction data for the specified account_id.

Parameters

Field Type Description
from datetime Return transactions posted on or after from date. Default now - 3 months
to datetime Returns transactions posted before to date. Default now

Response:

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

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
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 User input is required by the provider. user_input_required
404 The requested account cannot be found. account_not_found
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 current provider is unavailable under_maintenance

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