---
title: "Create a Connection"
method: POST
path: "/v3/data-connections"
tags: ["Connection Management"]
---

# Create a Connection

`POST /v3/data-connections`

Creates a connection resource.

This API must be called using a `client_credentials` bearer token.

## Headers

- `Tl-User-IP` string
- `X-Device-User-Agent` string

## Request body

- CreateConnection
  - `scopes` DataAccessScope[], required — The list of scopes that the user consents to. The Data Access endpoints return data only for the scopes that you request.
  - `provider_selection` union, required — Provider Selection
    - object — Indicates that the provider has been preselected for the end user.
      - `type` 'preselected', required — The type of provider.
      - `provider_id` string, required — The unique ID for the provider.
    - object — Indicates that the provider is to be selected from a collection
      - `type` 'user_selected', required — The type of provider.
      - `filter` ProviderFilter — Configuration options to constrain which providers should be available during the `provider_selection` action.
        - `countries` CountryCode[] — Only providers from the specified countries will be returned.
        - `release_channel` 'general_availability' | 'public_beta' | 'private_beta' — The lowest stability release stage of a provider that should be returned. Note that many EUR providers are in `public_beta` or `private_beta`.
        - `customer_segments` string[] — The customer segments that providers cater to that should be returned. By default, returns retail only.
        - `provider_ids` string[] — IDs of providers to include in those returned.
        - `excludes` object — Options to exclude providers included by the filters
          - `provider_ids` string[] — IDs of providers to explicitly exclude from those returned.
  - `user` ConnectionUserCreate, required — Details of the end user who is consenting to data access. If you are using your own Payment Initiation Service Provider (PISP) licence, these fields are not required. Otherwise `name` and one of `email`/`phone` are required.
    - `id` string — Unique ID for the User
    - `name` string — This is the full first and last name of your end user (not initials).
    - `email` string, email — The email address of your end user.
    - `phone` string, phone — The phone number of your end user in formats recommended by [ITU](https://www.itu.int/oth/T0202.aspx?parent=T0202). The country calling code must be included and prefixed with a `+`.
  - `metadata` Metadata — 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.
  - `user_consent` union, required — User consent
    - object — Indicates that the user has already consented to the connection.
      - `type` 'precaptured', required — The type of consent capture.
      - `captured_at` string, datetime, required — Timestamp the user consent was collected, in the UTC timezone.
    - object — Indicates that the user consent will be captured via the authorization flow.
      - `type` 'authorization_flow_captured', required — The type of consent capture.
  - `hosted_page` union — Configuration parameters for TrueLayer's hosted page(s), which are displayed to the user during the authorization journey. The type determines which parts of the flow TrueLayer handles.
    - object — Parameters for hosted page when used to display result page after the provider authentication.
      - `type` 'result_page', required — The type of hosted page.
      - `language_code` string — The language code of the user. This is used to determine which language to show on the hosted page, overriding the browser's locale. The language code must be in ISO 639-1 format.
    - object — Parameters for hosted page when used in the authorization flow. Set this to receive an automatically constructed hosted page URI in the response. This cannot be provided if the root-level authorization_flow parameter is also set.
      - `type` 'authorization_flow', required — The type of hosted page.
      - `return_uri` string, url, required — The URI where 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](/docs/app-settings#allowed-redirect-uris).
      - `country_code` string — The country code of the user. 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.
      - `language_code` string — The language code of the user. This is used to determine 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` AuthorizationFlowRequest — This object contains a declaration of your UI's capabilities. You cannot provide this if also using the hosted_page option with type=authorization_flow.
    - `redirect` object, required — Can your UI redirect the user to a third-party page? For most providers, the user authorises the connection after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the data access. This parameter states whether your UI can handle such a redirect.
      - `return_uri` string, required — During the flow, the end user authorises the connection on a third-party site, such as a bank. The return_uri you set is where the user is redirected to after they complete authorisation on the third-party site. You must register the return_uri in your [settings in Console](/docs/app-settings#allowed-redirect-uris).
  - `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.

## Response `201`

Connection

## Other responses

- `400` — Invalid Parameters
- `401` — Unauthenticated
- `403` — Forbidden
- `429` — Rate Limit Exceeded
- `500` — Unknown Error
- `502` — Provider Error

---

[API](https://skmtc.net/truelayer/apis/authentication-server.md) · [All operations](https://skmtc.net/truelayer/apis/authentication-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/truelayer/authentication-server/revisions/5f6051515b2c/schema)