TRtruelayer
Connection Management

Create a Connection

Creates a connection resource.

This API must be called using a client_credentials bearer token.

post/v3/data-connections

Request

  • Base URL
    https://api.truelayer-sandbox.com
  • URL
    https://api.truelayer-sandbox.com/v3/data-connections
  • Auth
    OAuth 2
    Client credentials
    Token URL: https://auth.truelayer.com/connect/token scopes: data

Headers

Tl-User-IPstring

Used to collect and record the end-user's IP address. The first IP address in the list will be used as the end-user IP address. Necessary to overcome 4 calls per day rate limits.

X-Device-User-Agentstring

Used to improve the end-user's authentication experience based on their device type. If omitted, the User-Agent header will be used instead. This header is only considered if the authorization_flow object in the request body is specified.

Request body

scopesDataAccessScope[] required

The list of scopes that the user consents to. The Data Access endpoints return data only for the scopes that you request.

metadataMetadata

Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters.

data_access_type'one_time' | 'recurring'

Determines how long access to the end user's bank data is maintained after the initial authorisation.

  • one_time — Data can only be retrieved within a single access window immediately after the user authorises with the bank. No further access is possible without a new connection.
  • recurring — Data can be retrieved repeatedly throughout the full consent window, even when the user is not actively logged in or present, without requiring the user to re-authorise with bank each time.

Example request

{
  "provider_selection": {
    "provider_id": "eg-provider"
  },
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c",
    "name": "Remi Terr",
    "email": "remi.terr@aol.com",
    "phone": "+447777777777"
  },
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "user_consent": {
    "captured_at": "2025-01-01T00:00:00.000Z"
  },
  "hosted_page": {
    "language_code": "de"
  },
  "authorization_flow": {
    "redirect": {
      "return_uri": "https://my-domain.com/my-return-page"
    }
  }
}

Response

Connection

OR

Example response

{
  "id": "0a6273a0-0314-4db6-800a-e66225fbe9f7",
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
  },
  "hosted_page": {
    "uri": "https://app.truelayer.com/data/0a6273a0-0314-4db6-800a-e66225fbe9f7?connection_id=9b7383a0-0314-4db6-800a-e66225fbe8g6"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.