---
updatedAt: 2026-06-22T09:14:45.000Z
agentTools:
  projectIndex: https://docs.truelayer.com/llms.txt
---

# Create a Connection

Creates a connection resource.

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


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Data API v3",
    "description": "Reference documentation for Data API v3\n",
    "version": "1",
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://api.truelayer-sandbox.com",
      "description": "Sandbox server"
    },
    {
      "url": "https://api.truelayer.com",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "Connection Management",
      "description": "Endpoints to manage data connections."
    },
    {
      "name": "Accounts",
      "description": "Endpoints to retrieve account data using a data connection."
    }
  ],
  "paths": {
    "/v3/data-connections": {
      "post": {
        "tags": [
          "Connection Management"
        ],
        "summary": "Create a Connection",
        "operationId": "create-connection",
        "description": "Creates a connection resource.\n\nThis API must be called using a `client_credentials` bearer token.\n",
        "security": [
          {
            "OAuth2": [
              "data"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/TlUserIpHeader",
            "description": "Used to collect and record the end-user's IP address.\nThe first IP address in the list will be used as the end user's IP address.\nThis header is only considered if the `authorization_flow` object in the request body is specified.\n"
          },
          {
            "$ref": "#/components/parameters/DeviceUserAgentHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConnection"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Connection",
            "headers": {
              "Tl-Trace-Id": {
                "$ref": "#/components/headers/Tl-Trace-Id"
              }
            },
            "content": {
              "application/json; charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedConnection"
                }
              }
            }
          },
          "400": {
            "description": "Invalid Parameters",
            "headers": {
              "Tl-Trace-Id": {
                "$ref": "#/components/headers/Tl-Trace-Id"
              }
            },
            "content": {
              "application/problem+json; charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsInvalidParameters"
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated",
            "headers": {
              "Tl-Trace-Id": {
                "$ref": "#/components/headers/Tl-Trace-Id"
              }
            },
            "content": {
              "application/problem+json; charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsUnauthenticated"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "headers": {
              "Tl-Trace-Id": {
                "$ref": "#/components/headers/Tl-Trace-Id"
              }
            },
            "content": {
              "application/problem+json; charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsForbidden"
                }
              }
            }
          },
          "429": {
            "description": "Rate Limit Exceeded",
            "headers": {
              "Tl-Trace-Id": {
                "$ref": "#/components/headers/Tl-Trace-Id"
              }
            },
            "content": {
              "application/problem+json; charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsRateLimitExceeded"
                }
              }
            }
          },
          "500": {
            "description": "Unknown Error",
            "headers": {
              "Tl-Trace-Id": {
                "$ref": "#/components/headers/Tl-Trace-Id"
              }
            },
            "content": {
              "application/problem+json; charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsUnknownError"
                }
              }
            }
          },
          "502": {
            "description": "Provider Error",
            "headers": {
              "Tl-Trace-Id": {
                "$ref": "#/components/headers/Tl-Trace-Id"
              }
            },
            "content": {
              "application/problem+json; charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsProviderError"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "connection_management": {
      "post": {
        "tags": [
          "Connection Management"
        ],
        "summary": "Connection Webhooks",
        "operationId": "connection-webhooks-management",
        "description": "Sent to the webhook URI that you registered when:\n- a connection is authorised.\n- a connection fails.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ConnectionAuthorized"
                  },
                  {
                    "$ref": "#/components/schemas/ConnectionFailed"
                  }
                ],
                "discriminator": {
                  "propertyName": "type",
                  "mapping": {
                    "connection_authorized": "#/components/schemas/ConnectionAuthorized",
                    "connection_failed": "#/components/schemas/ConnectionFailed"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook Handled"
          }
        },
        "security": []
      }
    },
    "transaction_requests": {
      "post": {
        "tags": [
          "Accounts"
        ],
        "summary": "Transactions request webhooks",
        "operationId": "transactions-request-webhooks",
        "description": "Sent to the configured webhook URI when an async transactions request reaches a terminal state:\n- The request completed successfully. Call `GET /v3/connected-accounts/{account_id}/transactions/requests/{request_id}` to retrieve the transactions.\n- The request failed.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/TransactionsRequestWebhookCompleted"
                  },
                  {
                    "$ref": "#/components/schemas/TransactionsRequestWebhookFailed"
                  }
                ],
                "discriminator": {
                  "propertyName": "type",
                  "mapping": {
                    "transactions_request_completed": "#/components/schemas/TransactionsRequestWebhookCompleted",
                    "transactions_request_failed": "#/components/schemas/TransactionsRequestWebhookFailed"
                  }
                }
              },
              "examples": {
                "transactions_request_completed_example": {
                  "summary": "Transactions request completed successfully",
                  "value": {
                    "type": "transactions_request_completed",
                    "event_version": 1,
                    "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
                    "connection_id": "7d4b7a2e-9f3c-4e8b-a1d5-6c2f8e0b3a7d",
                    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "completed_at": "2026-07-15T12:34:56.789Z"
                  }
                },
                "transactions_request_failed_example": {
                  "summary": "Transactions request failed",
                  "value": {
                    "type": "transactions_request_failed",
                    "event_version": 1,
                    "event_id": "c1e475a8-f838-4a35-95df-51465d66a61d",
                    "connection_id": "7d4b7a2e-9f3c-4e8b-a1d5-6c2f8e0b3a7d",
                    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "failure_reason": "provider_error",
                    "failed_at": "2026-07-15T12:34:56.789Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook Handled"
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.truelayer.com/connect/token",
            "scopes": {
              "data": "for accessing all the endpoints of Data API"
            }
          }
        }
      }
    },
    "parameters": {
      "TlUserIpHeader": {
        "in": "header",
        "name": "Tl-User-IP",
        "description": "Used to collect and record the end-user's IP address.\nThe first IP address in the list will be used as the end-user IP address.\nNecessary to overcome 4 calls per day rate limits.\n",
        "schema": {
          "type": "string"
        },
        "required": false
      },
      "DeviceUserAgentHeader": {
        "in": "header",
        "name": "X-Device-User-Agent",
        "description": "Used to improve the end-user's authentication experience based on their device type.\nIf omitted, the `User-Agent` header will be used instead.\nThis header is only considered if the `authorization_flow` object in the request body is specified.\n",
        "schema": {
          "type": "string"
        },
        "required": false
      },
      "WebhookSignatureHeader": {
        "in": "header",
        "name": "Tl-Signature",
        "description": "A JWS with detached content, verifiable with our public key.\nSee [Webhook Request Signing](/docs/configure-webhooks-for-your-integration#validate-the-signature-of-received-webhooks)\n",
        "schema": {
          "type": "string"
        },
        "required": true
      }
    },
    "schemas": {
      "ProblemDetailsInvalidParameters": {
        "title": "Invalid Parameters",
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "trace_id",
          "detail",
          "errors"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "https://docs.truelayer.com/docs/error-types#invalid-parameters"
            ]
          },
          "title": {
            "type": "string",
            "enum": [
              "Invalid Parameters"
            ]
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "enum": [
              400
            ]
          },
          "trace_id": {
            "type": "string",
            "description": "The TrueLayer trace identifier for the request",
            "example": "96ce50247f87f540bb2d86771b3728b8"
          },
          "detail": {
            "type": "string",
            "description": "A human-readable text with more information about why the error occurred.",
            "example": "The request body was invalid."
          },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 1
            },
            "example": {
              "Connection-Id": [
                "Must be provided"
              ]
            }
          }
        }
      },
      "ProblemDetailsUnauthenticated": {
        "title": "Unauthenticated",
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "trace_id",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "https://docs.truelayer.com/docs/error-types#unauthenticated"
            ]
          },
          "title": {
            "type": "string",
            "enum": [
              "Unauthenticated"
            ]
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "enum": [
              401
            ]
          },
          "trace_id": {
            "type": "string",
            "description": "The TrueLayer trace identifier for the request",
            "example": "96ce50247f87f540bb2d86771b3728b8"
          },
          "detail": {
            "type": "string",
            "description": "A human-readable text with more information about why the error occurred.",
            "example": "A Bearer token must be provided in the Authorization header."
          }
        }
      },
      "ProblemDetailsForbidden": {
        "title": "Forbidden",
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "trace_id",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "https://docs.truelayer.com/docs/error-types#forbidden"
            ]
          },
          "title": {
            "type": "string",
            "enum": [
              "Forbidden"
            ]
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "enum": [
              403
            ]
          },
          "trace_id": {
            "type": "string",
            "description": "The TrueLayer trace identifier for the request",
            "example": "96ce50247f87f540bb2d86771b3728b8"
          },
          "detail": {
            "type": "string",
            "description": "A human-readable text with more information about why the error occurred.",
            "example": "The token used for Authorization is not authorized to perform the request."
          }
        }
      },
      "ProblemDetailsRateLimitExceeded": {
        "title": "Rate Limit Exceeded",
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "trace_id",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "https://docs.truelayer.com/docs/error-types#rate-limit-exceeded"
            ]
          },
          "title": {
            "type": "string",
            "enum": [
              "Rate Limit Exceeded"
            ]
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "enum": [
              429
            ]
          },
          "trace_id": {
            "type": "string",
            "description": "The TrueLayer trace identifier for the request",
            "example": "96ce50247f87f540bb2d86771b3728b8"
          },
          "detail": {
            "type": "string",
            "description": "A human-readable text with more information about why the error occurred.",
            "example": "Too many API requests have been received within the allowed time frame."
          }
        }
      },
      "ProblemDetailsUnknownError": {
        "title": "Unknown Error",
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "trace_id",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "https://docs.truelayer.com/docs/error-types#unknown-error"
            ]
          },
          "title": {
            "type": "string",
            "enum": [
              "Unknown Error"
            ]
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "enum": [
              500
            ]
          },
          "trace_id": {
            "type": "string",
            "description": "The TrueLayer trace identifier for the request",
            "example": "96ce50247f87f540bb2d86771b3728b8"
          },
          "detail": {
            "type": "string",
            "description": "A human-readable text with more information about why the error occurred.",
            "example": "An error occurred. Please contact customer support."
          }
        }
      },
      "ProblemDetailsProviderError": {
        "title": "Provider Error",
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "trace_id",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "https://docs.truelayer.com/docs/error-types#provider-error"
            ]
          },
          "title": {
            "type": "string",
            "enum": [
              "Provider Error"
            ]
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "enum": [
              502
            ]
          },
          "trace_id": {
            "type": "string",
            "description": "The TrueLayer trace identifier for the request",
            "example": "96ce50247f87f540bb2d86771b3728b8"
          },
          "detail": {
            "type": "string",
            "description": "A human-readable text with more information about why the error occurred.",
            "example": "Provider is temporarily unavailable, please retry."
          }
        }
      },
      "TransactionsRequestFailureReason": {
        "type": "string",
        "description": "The reason the transactions request failed.\nThis list is non-exhaustive — integrators should handle unknown values gracefully.\n\nExamples:\n- `provider_error`\n",
        "example": "provider_error"
      },
      "DataAccessScope": {
        "type": "string",
        "title": "Data access scope",
        "enum": [
          "info",
          "accounts",
          "balance",
          "transactions"
        ]
      },
      "ProviderId": {
        "type": "string",
        "description": "The unique ID for the provider.",
        "example": "eg-provider"
      },
      "ProviderSelectionPreselected": {
        "title": "Preselected",
        "type": "object",
        "description": "Indicates that the provider has been preselected for the end user.",
        "required": [
          "type",
          "provider_id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of provider.",
            "enum": [
              "preselected"
            ]
          },
          "provider_id": {
            "$ref": "#/components/schemas/ProviderId"
          }
        }
      },
      "CountryCode": {
        "type": "string",
        "enum": [
          "AT",
          "BE",
          "DE",
          "DK",
          "ES",
          "FI",
          "FR",
          "GB",
          "IE",
          "IT",
          "LT",
          "NL",
          "NO",
          "PL",
          "PT",
          "RO"
        ]
      },
      "ProviderFilter": {
        "title": "Provider Filter",
        "type": "object",
        "description": "Configuration options to constrain which providers should be available\nduring the `provider_selection` action.\n",
        "properties": {
          "countries": {
            "type": "array",
            "description": "Only providers from the specified countries will be returned.",
            "items": {
              "$ref": "#/components/schemas/CountryCode"
            },
            "uniqueItems": true,
            "minItems": 1,
            "example": [
              "GB"
            ]
          },
          "release_channel": {
            "type": "string",
            "description": "The lowest stability release stage of a provider that should be returned.\n\nNote that many EUR providers are in `public_beta` or `private_beta`.\n",
            "default": "general_availability",
            "enum": [
              "general_availability",
              "public_beta",
              "private_beta"
            ],
            "example": "general_availability"
          },
          "customer_segments": {
            "type": "array",
            "description": "The customer segments that providers cater to that should be returned. By default, returns retail only.",
            "default": [
              "retail"
            ],
            "items": {
              "type": "string",
              "enum": [
                "retail",
                "business",
                "corporate"
              ]
            },
            "uniqueItems": true,
            "minItems": 1,
            "example": [
              "retail"
            ]
          },
          "provider_ids": {
            "type": "array",
            "description": "IDs of providers to include in those returned.",
            "items": {
              "type": "string"
            },
            "uniqueItems": true,
            "minItems": 1,
            "example": [
              "ob-bank"
            ]
          },
          "excludes": {
            "type": "object",
            "description": "Options to exclude providers included by the filters",
            "properties": {
              "provider_ids": {
                "type": "array",
                "description": "IDs of providers to explicitly exclude from those returned.",
                "items": {
                  "type": "string"
                },
                "uniqueItems": true,
                "minItems": 1,
                "example": [
                  "ob-exclude-this-bank"
                ]
              }
            }
          }
        }
      },
      "ProviderSelectionUserSelected": {
        "title": "User selected",
        "type": "object",
        "description": "Indicates that the provider is to be selected from a collection",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of provider.",
            "enum": [
              "user_selected"
            ]
          },
          "filter": {
            "$ref": "#/components/schemas/ProviderFilter"
          }
        }
      },
      "ProviderSelection": {
        "title": "Provider Selection",
        "type": "object",
        "description": "Provider Selection",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ProviderSelectionPreselected"
          },
          {
            "$ref": "#/components/schemas/ProviderSelectionUserSelected"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "preselected": "#/components/schemas/ProviderSelectionPreselected",
            "user_selected": "#/components/schemas/ProviderSelectionUserSelected"
          }
        }
      },
      "UserId": {
        "type": "string",
        "description": "Unique ID for the User",
        "example": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
      },
      "ConnectionUserCreate": {
        "title": "User",
        "type": "object",
        "description": "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.\n",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UserId",
            "description": "A unique identifier for the user. If you don’t provide this, TrueLayer generates a value in the response. You can use the same value for multiple connections to indicate a returning user."
          },
          "name": {
            "type": "string",
            "example": "Remi Terr",
            "description": "This is the full first and last name of your end user (not initials).\n",
            "pattern": "^[^\\(\\)]+$"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "remi.terr@aol.com",
            "description": "The email address of your end user.\n"
          },
          "phone": {
            "type": "string",
            "format": "phone",
            "example": "+447777777777",
            "description": "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 `+`.\n"
          }
        }
      },
      "Metadata": {
        "type": "object",
        "description": "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.",
        "maxProperties": 10,
        "additionalProperties": {
          "type": "string",
          "maxLength": 500
        },
        "example": {
          "prop1": "value1",
          "prop2": "value2"
        }
      },
      "UserConsentPrecaptured": {
        "title": "Pre-captured user consent",
        "type": "object",
        "description": "Indicates that the user has already consented to the connection.",
        "required": [
          "type",
          "captured_at"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of consent capture.",
            "enum": [
              "precaptured"
            ]
          },
          "captured_at": {
            "type": "string",
            "description": "Timestamp the user consent was collected, in the UTC timezone.",
            "format": "datetime",
            "example": "2025-01-01T00:00:00.000Z"
          }
        }
      },
      "UserConsentRequestAuthorizationFlowCaptured": {
        "title": "Authorization flow captured",
        "type": "object",
        "description": "Indicates that the user consent will be captured via the authorization flow.",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of consent capture.",
            "enum": [
              "authorization_flow_captured"
            ]
          }
        }
      },
      "UserConsentRequest": {
        "title": "User Consent",
        "type": "object",
        "description": "User consent",
        "oneOf": [
          {
            "$ref": "#/components/schemas/UserConsentPrecaptured"
          },
          {
            "$ref": "#/components/schemas/UserConsentRequestAuthorizationFlowCaptured"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "precaptured": "#/components/schemas/UserConsentPrecaptured",
            "authorization_flow_captured": "#/components/schemas/UserConsentRequestAuthorizationFlowCaptured"
          }
        }
      },
      "HostedPageParametersResultPage": {
        "title": "Result Page",
        "description": "Parameters for hosted page when used to display result page after the provider authentication.",
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of hosted page.",
            "enum": [
              "result_page"
            ]
          },
          "language_code": {
            "type": "string",
            "description": "The language code of the user. This is used to determine which language to show on the hosted page, overriding the browser's locale.\nThe language code must be in ISO 639-1 format.\n",
            "minLength": 2,
            "maxLength": 2,
            "pattern": "^[a-z]{2}$",
            "example": "de"
          }
        }
      },
      "HostedPageParametersAuthorizationFlow": {
        "title": "Authorization Flow",
        "description": "Parameters for hosted page when used in the authorization flow. Set this to receive an automatically constructed hosted page URI in the response. \nThis cannot be provided if the root-level `authorization_flow` parameter is also set.\n",
        "type": "object",
        "required": [
          "type",
          "return_uri"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of hosted page.",
            "enum": [
              "authorization_flow"
            ]
          },
          "return_uri": {
            "type": "string",
            "description": "The URI where the user will be redirected to after the authorization flow has completed on the hosted page.\nYou must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris).\n",
            "format": "url",
            "example": "https://my-domain.com/my-return-page"
          },
          "country_code": {
            "type": "string",
            "description": "The country code of the user. This is used to determine which banks to show on the hosted page initially.\nThe country code must be in ISO 3166-1 alpha-2 format.\n",
            "minLength": 2,
            "maxLength": 2,
            "pattern": "^[A-Z]{2}$",
            "example": "DE"
          },
          "language_code": {
            "type": "string",
            "description": "The language code of the user. This is used to determine which language to show on the hosted page, overriding the browser's locale.\nThe language code must be in ISO 639-1 format.\n",
            "minLength": 2,
            "maxLength": 2,
            "pattern": "^[a-z]{2}$",
            "example": "de"
          }
        }
      },
      "HostedPageParameters": {
        "title": "Hosted Page Parameters",
        "type": "object",
        "description": "Configuration parameters for TrueLayer's hosted pages, which are displayed to the user during the authorization journey. The type determines which parts of the flow TrueLayer handles.\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/HostedPageParametersResultPage"
          },
          {
            "$ref": "#/components/schemas/HostedPageParametersAuthorizationFlow"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "result_page": "#/components/schemas/HostedPageParametersResultPage",
            "authorization_flow": "#/components/schemas/HostedPageParametersAuthorizationFlow"
          }
        }
      },
      "ReturnUri": {
        "type": "string",
        "description": "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.\n\nYou must register the return URI in your [settings in Console](/docs/app-settings#allowed-redirect-uris).\n",
        "example": "https://my-domain.com/my-return-page"
      },
      "AuthorizationFlowRequest": {
        "type": "object",
        "title": "Authorization flow",
        "description": "This object contains a declaration of your UI's capabilities.\nYou cannot provide this if also using the `hosted_page` option with `type=authorization_flow`.\n",
        "required": [
          "redirect"
        ],
        "properties": {
          "redirect": {
            "type": "object",
            "title": "Redirect",
            "description": "Can your UI redirect the user to a third-party page?\nFor 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.\n",
            "required": [
              "return_uri"
            ],
            "properties": {
              "return_uri": {
                "$ref": "#/components/schemas/ReturnUri"
              }
            }
          }
        }
      },
      "DataAccessType": {
        "type": "string",
        "title": "Data access type",
        "description": "Determines how long access to the end user's bank data is maintained after the initial authorisation.\n- `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.\n- `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.\n",
        "enum": [
          "one_time",
          "recurring"
        ],
        "default": "recurring"
      },
      "CreateConnection": {
        "type": "object",
        "title": "Create connection",
        "required": [
          "scopes",
          "provider_selection",
          "user",
          "user_consent"
        ],
        "properties": {
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DataAccessScope"
            },
            "minItems": 1,
            "description": "The list of scopes that the user consents to. The Data Access endpoints return data only for the scopes that you request.\n"
          },
          "provider_selection": {
            "$ref": "#/components/schemas/ProviderSelection"
          },
          "user": {
            "$ref": "#/components/schemas/ConnectionUserCreate"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "user_consent": {
            "$ref": "#/components/schemas/UserConsentRequest"
          },
          "hosted_page": {
            "$ref": "#/components/schemas/HostedPageParameters"
          },
          "authorization_flow": {
            "$ref": "#/components/schemas/AuthorizationFlowRequest"
          },
          "data_access_type": {
            "$ref": "#/components/schemas/DataAccessType"
          }
        }
      },
      "ConnectionId": {
        "type": "string",
        "description": "Unique ID for the connection",
        "example": "0a6273a0-0314-4db6-800a-e66225fbe9f7"
      },
      "ConnectionUser": {
        "title": "User",
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UserId"
          }
        }
      },
      "ConnectionCreatedCommon": {
        "title": "Newly created connection",
        "type": "object",
        "required": [
          "id",
          "user"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ConnectionId"
          },
          "user": {
            "$ref": "#/components/schemas/ConnectionUser"
          }
        }
      },
      "HostedPage": {
        "title": "Hosted Page",
        "description": "Returned if the `hosted_page` object in the request body is populated.\n",
        "type": "object",
        "required": [
          "uri"
        ],
        "properties": {
          "uri": {
            "type": "string",
            "description": "The URI to redirect the user to, in order to authorize the connection using the hosted page.\n",
            "format": "url",
            "example": "https://app.truelayer.com/data/0a6273a0-0314-4db6-800a-e66225fbe9f7?connection_id=9b7383a0-0314-4db6-800a-e66225fbe8g6"
          }
        }
      },
      "ConnectionCreatedAuthorizationRequired": {
        "title": "Authorization Required",
        "allOf": [
          {
            "$ref": "#/components/schemas/ConnectionCreatedCommon"
          },
          {
            "type": "object",
            "required": [
              "status"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "authorization_required"
                ]
              },
              "hosted_page": {
                "$ref": "#/components/schemas/HostedPage"
              }
            }
          }
        ]
      },
      "ActionSpecRedirect": {
        "type": "object",
        "title": "Redirect",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "redirect"
            ]
          },
          "uri": {
            "type": "string",
            "format": "url",
            "description": "URL the end user must be redirected to.\n"
          }
        },
        "required": [
          "type",
          "uri"
        ]
      },
      "Provider": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ProviderId"
          },
          "display_name": {
            "type": "string",
            "example": "Bank Name"
          },
          "icon_uri": {
            "type": "string",
            "format": "uri",
            "example": "https://truelayer-provider-assets.s3.amazonaws.com/global/icon/generic.svg"
          },
          "logo_uri": {
            "type": "string",
            "format": "uri",
            "example": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic.svg"
          },
          "bg_color": {
            "type": "string",
            "description": "pattern: `^#[A-F0-9]{6}$`",
            "pattern": "^#[A-F0-9]{6}$",
            "example": "#000000"
          }
        }
      },
      "ActionSpecProviderSelection": {
        "type": "object",
        "title": "Provider Selection",
        "description": "Provider selection represents the end user's action of selecting a provider\n",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "provider_selection"
            ]
          },
          "providers": {
            "type": "array",
            "description": "List of providers to be presented to the end user.",
            "items": {
              "$ref": "#/components/schemas/Provider"
            }
          },
          "user_recommended_provider_ids": {
            "type": "array",
            "description": "List of recommended providers for the user, in order of most to least recommended.\nNote that this is only populated if `user_recommended_provider_ids` is set to `true` when starting the authorization flow, and TrueLayer has recommendations for the user.\n",
            "items": {
              "$ref": "#/components/schemas/ProviderId"
            }
          }
        },
        "required": [
          "type",
          "providers"
        ]
      },
      "NextAction": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ActionSpecRedirect"
          },
          {
            "$ref": "#/components/schemas/ActionSpecProviderSelection"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "redirect": "#/components/schemas/ActionSpecRedirect",
            "provider_selection": "#/components/schemas/ActionSpecProviderSelection"
          }
        }
      },
      "ConnectionAuthorizationFlow": {
        "type": "object",
        "title": "Authorization Flow",
        "description": "Contains information regarding the nature and the state of the authorization flow \n",
        "required": [
          "actions"
        ],
        "properties": {
          "actions": {
            "type": "object",
            "required": [
              "next"
            ],
            "properties": {
              "next": {
                "$ref": "#/components/schemas/NextAction"
              }
            }
          }
        }
      },
      "ConnectionCreatedAuthorizing": {
        "title": "Authorizing",
        "allOf": [
          {
            "$ref": "#/components/schemas/ConnectionCreatedCommon"
          },
          {
            "type": "object",
            "required": [
              "status",
              "authorization_flow"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "authorizing"
                ]
              },
              "authorization_flow": {
                "$ref": "#/components/schemas/ConnectionAuthorizationFlow",
                "description": "Contains information regarding the nature and the state of the authorization flow. This object will have a value only if in the request body the `authorization_flow` field was specified."
              }
            }
          }
        ]
      },
      "CreatedConnection": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ConnectionCreatedAuthorizationRequired"
          },
          {
            "$ref": "#/components/schemas/ConnectionCreatedAuthorizing"
          }
        ],
        "discriminator": {
          "propertyName": "status",
          "mapping": {
            "authorization_required": "#/components/schemas/ConnectionCreatedAuthorizationRequired",
            "authorizing": "#/components/schemas/ConnectionCreatedAuthorizing"
          }
        }
      },
      "WebhookCommon": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "event_version": {
            "description": "The version of the event schema.\n",
            "type": "integer"
          },
          "event_id": {
            "description": "Unique ID of the event.\n",
            "type": "string",
            "example": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941"
          }
        },
        "required": [
          "type",
          "event_version",
          "event_id"
        ]
      },
      "AuthorizedAt": {
        "type": "string",
        "description": "The date and time the connection was authorized.",
        "format": "datetime",
        "example": "2025-01-01T09:01:00.000Z"
      },
      "ConnectionAuthorized": {
        "title": "Authorized",
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookCommon"
          },
          {
            "type": "object",
            "required": [
              "type",
              "event_version",
              "connection_id",
              "authorized_at"
            ],
            "properties": {
              "type": {
                "enum": [
                  "connection_authorized"
                ]
              },
              "event_version": {
                "enum": [
                  1
                ]
              },
              "connection_id": {
                "$ref": "#/components/schemas/ConnectionId"
              },
              "metadata": {
                "$ref": "#/components/schemas/Metadata"
              },
              "authorized_at": {
                "$ref": "#/components/schemas/AuthorizedAt"
              }
            }
          }
        ]
      },
      "FailedAt": {
        "type": "string",
        "description": "The date and time the connection failed.",
        "format": "datetime",
        "example": "2025-01-01T09:01:00.000Z"
      },
      "ConnectionFailureStage": {
        "type": "string",
        "enum": [
          "authorization_required",
          "authorizing"
        ],
        "description": "The status the connection was in when it failed.\n",
        "example": "authorizing"
      },
      "ConnectionFailureReason": {
        "type": "string",
        "description": "The reason that the connection failed.\n",
        "example": "provider_rejected"
      },
      "ConnectionFailed": {
        "title": "Failed",
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookCommon"
          },
          {
            "type": "object",
            "required": [
              "type",
              "event_version",
              "connection_id",
              "failed_at",
              "failure_stage",
              "failure_reason"
            ],
            "properties": {
              "type": {
                "enum": [
                  "connection_failed"
                ]
              },
              "event_version": {
                "enum": [
                  1
                ]
              },
              "connection_id": {
                "$ref": "#/components/schemas/ConnectionId"
              },
              "metadata": {
                "$ref": "#/components/schemas/Metadata"
              },
              "failed_at": {
                "$ref": "#/components/schemas/FailedAt"
              },
              "failure_stage": {
                "$ref": "#/components/schemas/ConnectionFailureStage"
              },
              "failure_reason": {
                "$ref": "#/components/schemas/ConnectionFailureReason"
              }
            }
          }
        ]
      },
      "AccountId": {
        "type": "string",
        "description": "Unique ID for the connected account.",
        "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "RequestId": {
        "type": "string",
        "format": "uuid",
        "description": "Unique ID of the async request.",
        "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "TransactionsRequestCompletedAt": {
        "type": "string",
        "description": "The date and time the transactions request completed.",
        "format": "date-time",
        "example": "2025-01-01T09:01:00.000Z"
      },
      "TransactionsRequestWebhookCompleted": {
        "title": "Transactions request webhook (completed)",
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookCommon"
          },
          {
            "type": "object",
            "required": [
              "type",
              "event_version",
              "connection_id",
              "account_id",
              "request_id",
              "completed_at"
            ],
            "properties": {
              "type": {
                "enum": [
                  "transactions_request_completed"
                ]
              },
              "event_version": {
                "enum": [
                  1
                ]
              },
              "connection_id": {
                "$ref": "#/components/schemas/ConnectionId"
              },
              "account_id": {
                "$ref": "#/components/schemas/AccountId"
              },
              "request_id": {
                "$ref": "#/components/schemas/RequestId"
              },
              "completed_at": {
                "$ref": "#/components/schemas/TransactionsRequestCompletedAt"
              }
            }
          }
        ]
      },
      "TransactionsRequestFailedAt": {
        "type": "string",
        "description": "The date and time the transactions request failed.",
        "format": "date-time",
        "example": "2025-01-01T09:01:00.000Z"
      },
      "TransactionsRequestWebhookFailed": {
        "title": "Transactions request webhook (failed)",
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookCommon"
          },
          {
            "type": "object",
            "required": [
              "type",
              "event_version",
              "connection_id",
              "account_id",
              "request_id",
              "failure_reason",
              "failed_at"
            ],
            "properties": {
              "type": {
                "enum": [
                  "transactions_request_failed"
                ]
              },
              "event_version": {
                "enum": [
                  1
                ]
              },
              "connection_id": {
                "$ref": "#/components/schemas/ConnectionId"
              },
              "account_id": {
                "$ref": "#/components/schemas/AccountId"
              },
              "request_id": {
                "$ref": "#/components/schemas/RequestId"
              },
              "failure_reason": {
                "$ref": "#/components/schemas/TransactionsRequestFailureReason"
              },
              "failed_at": {
                "$ref": "#/components/schemas/TransactionsRequestFailedAt"
              }
            }
          }
        ]
      }
    },
    "headers": {
      "Tl-Trace-Id": {
        "schema": {
          "type": "string"
        },
        "description": "Unique ID per request.\nWe recommend logging this to share with us when investigating any issues.\n"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```