Create a connection

A connection, in Data V3, allows you to access a user's bank account information. Make a POST request to the /v3/data-connections endpoint to create this resource.

You need the connection ID, which results from a connection that you create and your user authorises, to make any further Data v3 API requests (either as a path parameter, or as a header).

Authentication

This endpoint requires you to pass a valid Bearer access token with the data scope as a header.

You may also want to provide the IP address of the end user as a header. This confirms that your user is present when the request is made, enabling you to bypass rate limiting.

Make a create connection request

This table contains an overview of all possible parameters inside a create connection request. These control the types of information that you will have access to, the length of time that you will have that access for, and which screens of the authorisation flow UI are yours instead of TrueLayer's (if any).

When creating a connection via POST /v3/data-connections, you choose how much of the authorization journey TrueLayer handles versus your own UI. There are five supported configurations, controlled by the combination of hosted_page, authorization_flow, provider_selection, and user_consent fields.

Field	Type	Required?	Description
`scopes`	array of strings	Yes	Can be `info`, `accounts`, `balance`, `transactions`. This describes what information you are asking your user to consent to sharing when they authorise the connection.
`provider_selection`	object	Yes	Determines how the bank/provider is chosen. Can be either `preselected` (you specify the provider, eg if you've built your own provider selection UI and only need to pass a `provider_id`) or `user_selected` (the user picks from a list).
`provider_selection.type`	string (enum)	Yes	Can be `preselected` or `user_selected`.
`provider_selection.filter`	object	No	An object in which you can control what providers are included on a TrueLayer provider selection UI. Contains: `countries`, in which you list country codes to specify which countries' providers appear to select from `release_channel`, in which you specify whether to include banks in `general_availability` only, or also include `private_beta` and `public_beta` banks. Note that specifying `private_beta` will result in private beta and general availability banks appearing in the list; `public_beta` will result in public beta, private beta and general availability banks appearing. `customer_segments`, in which you specify what kind of customer segments the providers in the list cater to (can be `retail`, `business` and/or `corporate`) `provider_ids`, in which you can supply an array of provider IDs that are not covered by any of the filters above to be included on the list `excludes`, in which you can specify provider IDs to exclude from the list
`provider_selection.provider_id`	string	Yes if `provider_selection.type` is `preselected`	The `provider_id` of a preselected provider.
`user`	object	Yes	Details of the end user consenting to data access. Name and either email or phone are required.
`user.id`	string	No	The ID associated with a specific user. If not provided, TrueLayer will create one.
`user.name`	string	Yes (unless you have an AISP licence)	The name of your user.
`user.email`	string	Yes (if not providing phone or you have an AISP licence)	An email address belonging to your user.
`user.phone`	string	Yes (if not providing email or you have an AISP licence)	A phone number belonging to your user.
`metadata`	object	No	Supports up to 10 key-value pairs, with keys up to 40 characters each and values up to 500 characters each.
`user_consent`	object	Yes	Captures how user consent was obtained.
`user_consent.type`	object	Yes	Can be `precaptured` (consent was collected outside of TrueLayer's flow) or `authorization_flow_captured` (TrueLayer captures it during the auth journey).
`user.consent.captured_at`	object	Yes	Only appears if the value of `authorization_flow_captured.type` is `precaptured`. A timestamp representing the time at which your user gave consent, if you're not
`hosted_page`	object	No	Configuration for TrueLayer's hosted page(s) shown during the authorisation journey. The type field controls which parts of the flow TrueLayer handles (eg `result_page` or `authorization_flow`).
`hosted_page.type`	string	Yes (if you're using a `hosted_page` object)	Can be `result_page` or `authorization_flow`. If you set this to `result_page`, this object configures the appearance of a result page after your user has authenticated with their provider. Use this if your user has already authorised the data connection using your own flow. This means the rest of the TrueLayer flow doesn't appear -- you will only see our result screen. You must handle the rest of the authorisation flow. If you set this to `authorization_flow`, you receive an automatically constructed hosted page URI in the response which contains the entire authorization flow including provider selection. This will not be provided if the root-level `authorization_flow` parameter is also set.
`hosted_page.return_uri`	string	Yes (if you're using a `hosted_page` object)	The URI that the user will be redirected to after the authorization flow has completed on the hosted page. You must register the return_uri in your settings in Console.
`hosted_page.country_code`	string	No	A country code which indicates where the user is based. This is used to determine which banks to show on the hosted page initially. The country code must be in ISO 3166-1 alpha-2 format.
`hosted_page.language_code`	string	No	This determines which language to show on the hosted page, overriding the browser's locale. The language code must be in ISO 639-1 format.
`authorization_flow`	object	No	A declaration of your own UI's capabilities, used when you are building a custom authorisation flow. This cannot be used alongside `hosted_page` with `type=authorization_flow`. [this is assuming you're not using our UIs, except for certain features like QR code handoff]
`authorization_flow.redirect`	object	No
`authorization_flow.redirect.return_uri`	string (URL)	No
`data_access_type`	string (enum)	No	Controls the duration of data access after initial authorisation. `one_time` limits access to a single window immediately after authorisation; `recurring` allows repeated access throughout the full consent window without requiring re-authorisation. By default, the value for this field is `recurring`.

Depending on which of our UI screens you want to use -- if any -- choose from one of the configurations below.

If you want to use our hosted UI

This configuration is best for getting started quickly, or if you don't want to build any authorization UI.

Use these parameters if you want TrueLayer's hosted page to manage the entire flow: bank selection, consent, bank redirect, and a results screen. On desktop, users are shown a QR code to complete the journey on mobile.

{
  "scopes": ["accounts", "transactions"],
  "provider_selection": {
    "type": "user_selected"
  },
  "user_consent": {
    "type": "authorization_flow_captured"
  },
  "hosted_page": {
    "type": "authorization_flow",
    "return_uri": "https://your-app.com/callback"
  }
}

The connection will have the status of authorization_required when you complete the request. Redirect the user to your specified return URI.

If you want to use your own provider selection screen but our hosted UI everywhere else

Use this configuration when you have your own bank picker UI but want TrueLayer to handle consent, the bank redirect, and result screen.

{
  "scopes": ["accounts", "transactions"],
  "provider_selection": {
    "type": "preselected",
    "provider_id": "ob-monzo"
  },
  "user_consent": {
    "type": "authorization_flow_captured"
  },
  "hosted_page": {
    "type": "authorization_flow",
    "return_uri": "https://your-app.com/callback"
  }
}

The connection will have the status of authorization_required when you complete the request. Redirect the user to your specified return URI.

If you want to handle everything except QR code handoff and result screen

Use this configuration when you have your own bank picker and consent UI, but want TrueLayer to handle the desktop-to-mobile QR code handoff and show a results screen.

{
  "scopes": ["accounts", "transactions"],
  "provider_selection": {
    "type": "preselected",
    "provider_id": "ob-monzo"
  },
  "user_consent": {
    "type": "precaptured",
    "captured_at": "2025-01-01T12:00:00Z"
  },
  "hosted_page": {
    "type": "authorization_flow",
    "return_uri": "https://your-app.com/callback"
  }
}

The connection will have the status of authorization_required when you complete the request. Redirect the user to your specified return URI.

If you want to handle everything except the result screen

Use this configuration when you have a fully custom authorization journey but want TrueLayer to display a result screen after bank authorization completes. No QR code handoff in this configuration — the client owns the bank redirect, so TrueLayer cannot intercept to show a QR code.

{
  "scopes": ["accounts", "transactions"],
  "provider_selection": {
    "type": "preselected",
    "provider_id": "ob-monzo"
  },
  "user_consent": {
    "type": "precaptured",
    "captured_at": "2025-01-01T12:00:00Z"
  },
  "hosted_page": {
    "type": "result_page",
    "return_uri": "https://your-app.com/callback"
  }
}

The connection will have a status of authorizing if this request succeeds — redirect the user to the bank authorization URL in authorization_flow.actions.next.uri

If you want to handle the entire end-user journey end to end

Fully regulated clients who want complete control over the entire authorization journey with no TrueLayer UI at all.

{
  "scopes": ["accounts", "transactions"],
  "provider_selection": {
    "type": "preselected",
    "provider_id": "ob-monzo"
  },
  "user_consent": {
    "type": "precaptured",
    "captured_at": "2025-01-01T12:00:00Z"
  },
  "authorization_flow": {
    "redirect": {
      "return_uri": "https://your-app.com/callback"
    }
  }
}

The connection will have the status of authorizing if the request succeeds. Redirect the user to the bank authorization URL in authorization_flow.actions.next.uri

Below is a full example request. In this example, TrueLayer's UI is set to be used for the entire end-user journey.

{
  "provider_selection": {
    "type": "user_selected",
    "filter": {
      "countries": ["GB"],
      "release_channel": "public",
      "customer_segments": ["retail"]
    }
  },
  "hosted_page": {
    "type": "authorization_flow",
    "redirect": {
      "return_uri": "https://yourapp.com/callback"
    }
  },
  "scopes": [
    "accounts",
    "transactions",
  ],
  "user": {
    "name": "Jane Smith",
    "email": "[email protected]",
    "phone": "+447700900000"
  },
  "user_consent": {
    "type": "authorization_flow_captured"
  },
  "data_access_type": "recurring"
}

Response

Below is an example response. The response contains a user ID, connection ID, connection status and hosted page URI:

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

You must then use the connection ID as a header in future data requests.