Data API v1 overview

📘
Integrating for the first time?
If this is your first time integrating with a Data product, use the Data API v3.
These docs are specifically about Data v1. While v1 and v3 both enable the same use cases, the integration processes for each version of the product are significantly different.

Available data

The Data API allows you to access the following data for connected accounts available from a provider:

Account: account holder name, account number, IBAN etc
Credit card: card network, last four digits, name on card etc
Transactions: description, amount, category, merchant name etc
Balances: current, available etc
Regular payments: standing orders and direct debits

Use /api/providers endpoint to determine which data is available for each provider. The response includes scopes which contains a list of information relating to the account.

Supported countries

See our Supported Providers page in Console for more info on which countries and providers we support.

Authentication flow

We offer a ready-made UX flow for you to easily let users connect their bank accounts to your application, or you can build your own fully custom flow on top of our API.

If you are regulated, you have 2 options for your auth flow:

Use our ready-made, customisable user journey
Build your own

📘
Non-regulated and agents of TrueLayer customers must use TrueLayer’s flow, which is customisable to fit seamlessly into your application.

Both regulated and non-regulated merchants can also:

Easily reconnect with lapsed account connections with our re-authentication process.
Understand how far users make it through the authentication journey with our auth journey analytics (private beta).

Data types

General

All of the responses returned by TrueLayer APIs 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

ISO20022 Text Fields

The Data API constrains some fields to be limited to ISO 20022 text format. These fields are typically used for names and references in bank payment requests.

Valid characters for such a text field include:

a-z
A-Z
0-9
/ – ? : ( ) . , ‘ +
space

Any other characters will result in a validation error.

API response structure

All responses are JSON encoded.

Success

Field name	Type	Description
`results`	array	An array of objects

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

Error

Most Data API v1 calls return the

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":  "internal_error",
    "error_description": "Well, this is embarrassing!",
    "error_details": {
        "detail_key": "detail value"
    }
}

The only exception to this is the error response for the /connections/extend endpoint. Error responses for this endpoint contain the following fields:

Field name	Type	Required?	Description
`type`	string	Yes	A URI identifying the class of error. It's a stable link to documentation describing this error type, so you can branch on it programmatically and click through for more detail.
`title`	string	Yes	A short, human-readable summary of the error type. It stays the same for a given type and isn't specific to this individual occurrence.
`status`	string	Yes	The HTTP status code, repeated in the body. 400 indicates the request was invalid — in this case, a validation failure.
`instance`	string	Yes	The endpoint where the error occurred (the request path that failed).
`trace_id`	string	Yes	A unique identifier for this specific request. Log it and quote it to TrueLayer support when raising a ticket, as it's how we locate your exact call.
`errors`	object	No	Field-level validation detail. An object mapping each offending request field to an array of human-readable messages explaining what's wrong. A field can have multiple messages, and multiple fields can appear.

{
  "type": "https://docs.truelayer.com/#connection-api-errors",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "/connections/extend",
  "trace_id": "3dc845a2-93a2-4e12-940a-0a8aec24d0bc",
  "errors": {
    "ClientId": [
      "The ClientId field is required."
    ]
  }
}