> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a link intent

> Creates a link intent, the first step to connect an account through the Fintoc widget. The response includes the `widget_token` needed to initialize the widget; Fintoc returns the token only in this response. The link intent inherits the `live` or `test` mode of the API key used.

**`v1`** · Base URL `https://api.fintoc.com/v1`


## OpenAPI

````yaml reference/fintoc-api.json POST /link_intents
openapi: 3.1.0
info:
  title: fintoc-api
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v1
security: []
paths:
  /link_intents:
    post:
      tags:
        - Link intents
      summary: Create a link intent
      description: >-
        Creates a link intent, the first step to connect an account through the
        Fintoc widget. The response includes the `widget_token` needed to
        initialize the widget; Fintoc returns the token only in this response.
        The link intent inherits the `live` or `test` mode of the API key used.
      operationId: link-intents-create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                country:
                  type: string
                  enum:
                    - cl
                  description: >-
                    ISO 3166-1 alpha-2 code of the country of the institution to
                    connect.
                  example: cl
                holder_type:
                  type: string
                  enum:
                    - individual
                    - business
                  example: business
                  description: >-
                    Whether the credentials to connect belong to an individual
                    or a business.
                product:
                  type: string
                  enum:
                    - movements
                  example: movements
                  description: Fintoc product that the resulting link will be used for.
              required:
                - country
                - holder_type
                - product
            examples:
              create_link_intent:
                summary: Create a link intent
                value:
                  country: cl
                  holder_type: business
                  product: movements
      responses:
        '201':
          description: >-
            Link intent created. The `widget_token` is only returned in this
            response.
          content:
            application/json:
              examples:
                link_intent_created:
                  value:
                    id: li_a6WUojQ2SjSSeFjH
                    object: link_intent
                    country: cl
                    created_at: '2022-12-01T01:50:12Z'
                    exchange_token: null
                    exchange_token_expires_at: null
                    holder_type: business
                    mode: live
                    product: movements
                    status: created
                    widget_token: li_a6WUojQ2SjSSeFjH_sec_Q802GD8ZLmMuK0Atl4ucJuLp
              schema:
                $ref: '#/components/schemas/link_intent'
        '400':
          description: >-
            Invalid request: a required param is missing, or the `product`,
            `country` or `holder_type` is not supported.
          content:
            application/json:
              examples:
                not_supported_product:
                  value:
                    error:
                      type: invalid_request_error
                      code: not_supported_product
                      param: product
                      message: >-
                        Not supported product: payments. Currently, supported
                        products are: movements.
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              examples:
                invalid_api_key:
                  value:
                    error:
                      type: authentication_error
                      code: invalid_api_key
                      message: 'Invalid API Key: invalid-*oken'
              schema:
                $ref: '#/components/schemas/error_object'
      security:
        - api_key: []
components:
  schemas:
    link_intent:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the link intent.
          example: li_a6WUojQ2SjSSeFjH
        object:
          const: link_intent
          description: Type of the object. Always `link_intent`.
        country:
          type: string
          enum:
            - cl
          description: >-
            ISO 3166-1 alpha-2 code of the country of the institution to
            connect.
          example: cl
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the link intent was created.
          example: '2022-12-01T01:50:12Z'
        exchange_token:
          type:
            - string
            - 'null'
          description: >-
            Token used to retrieve the resulting link from your backend once the
            link intent succeeds. Only returned by the widget when the
            connection succeeds; `null` in every other response.
          example: li_a6WUojQ2SjSSeFjH_exc_Q802GD8ZLmMuK0Atl4ucJuLp
        exchange_token_expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            ISO 8601 timestamp of when the `exchange_token` expires. `null` if
            no exchange token has been issued.
          example: '2022-12-01T02:50:12Z'
        holder_type:
          type: string
          enum:
            - individual
            - business
          description: >-
            Whether the credentials to connect belong to an individual or a
            business.
          example: individual
        mode:
          type: string
          enum:
            - live
            - test
          description: >-
            Mode of the link intent. `live` connects to real institutions,
            `test` connects to the test institution with fake data.
          example: live
        product:
          type: string
          enum:
            - movements
          description: Fintoc product the resulting link will be used for.
          example: movements
        status:
          type: string
          enum:
            - created
            - in_progress
            - succeeded
            - failed
            - rejected
          description: >-
            Status of the link intent. `rejected` means the institution rejected
            the credentials, `failed` means an error kept the connection from
            completing.
          example: created
        widget_token:
          type:
            - string
            - 'null'
          description: >-
            Token used to initialize the Fintoc widget for this link intent.
            Only returned when the link intent is created; `null` in every other
            response.
          example: li_a6WUojQ2SjSSeFjH_sec_Q802GD8ZLmMuK0Atl4ucJuLp
      required:
        - id
        - object
        - widget_token
        - status
        - holder_type
        - product
        - country
        - mode
        - exchange_token
        - exchange_token_expires_at
        - created_at
    error_object:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_api_key`. Not returned by every error.
              example: invalid_api_key
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Invalid API Key: invalid-*oken'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. `null` when
                the error cannot be tied to a single parameter, and not returned
                by every error.
              example: amount
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error`,
                `authentication_error`, or `api_error`.
              example: invalid_request_error
          required:
            - type
            - message
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````