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

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

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"
response_mode MUST be: "form_post"
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 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

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

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

Success response

{
    "results": [
        {
            "hello": "world"
        }
    ],
    "success": true
}

Error response

{
    "error": {
        "code": "internal_error",
        "message": "This embarrassing!"
    },
    "success": false
}

All responses are JSON encoded and includes the following fields

Field name Type Description
success boolean A boolean value that indicates if the request has been successful or not
error object If an error occurred, this field will be an object with a code and a message fields
results array An array of objects

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"
        }
    ], 
    "success": true
}

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"
        }
    ], 
    "success": true
}

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
{
  "success": true,
  "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

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}
{
  "success": true,
  "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]
accountNumber.iban string ISO 13616-1:2007 international bank number
accountNumber.number string Bank account number
accountNumber.sort_code string United Kingdom SORT code
accountNumber.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 *acc

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
{
  "success": true,
  "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 timestamp Last update time

Retrieve account transactions

GET: /accounts/v1/{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}"
{
  "success": true,
  "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 timestamp Return transactions posted on or after from date
to timestamp Returns transactions posted before to date

Response:

Field Type Description
timestamp timestamp 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

Error codes

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

HTTP Status Description Error Code
200 Success
400 bad_request
403 access_denied
404 account_not_found
500 Internal server error internal_error