openapi: 3.1.0
info:
  title: Accounting subpackage_linkToken API
  version: 1.0.0
servers:
- url: https://api.merge.dev/api
- url: https://api-eu.merge.dev/api
- url: https://api-ap.merge.dev/api
tags:
- name: subpackage_linkToken
paths:
  /accounting/v1/link-token:
    post:
      operationId: create
      summary: Create
      description: Creates a link token to be used when linking a new end user. The link token expires after single use.
      tags:
      - subpackage_linkToken
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDetailsRequest'
  /api/v1/registered-users/{registered_user_id}/link-token/:
    post:
      operationId: create-for-registered-user
      summary: Create Link token
      description: Generates a Link Token for a Registered User to authenticate with Connectors. Also returns a magic link URL that can be shared with the user to authenticate in a browser.
      tags:
      - subpackage_linkToken
      parameters:
      - name: registered_user_id
        in: path
        description: Agent Handler ID of the Registered User
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/linkToken_createForRegisteredUser_Response_201'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                connector:
                  type: string
                  description: Slug of the connector to generate a link token for
                external_id:
                  type:
                  - string
                  - 'null'
                  description: Optional external ID to scope the link token to a specific application credential. Use this when you have multiple OAuth apps for the same connector.
                callback_url:
                  type:
                  - string
                  - 'null'
                  description: Optional URL to redirect the user to after they complete the authentication flow. Must be added to your organization's allowed callback origins first.
                state:
                  type:
                  - string
                  - 'null'
                  description: Optional CSRF protection token returned to your callback_url after authentication. Requires callback_url to be set. Do not include a 'state' query parameter in callback_url if using this field.
              required:
              - connector
  /ats/v1/link-token:
    post:
      operationId: create
      summary: Create
      description: Creates a link token to be used when linking a new end user. The link token expires after single use.
      tags:
      - subpackage_linkToken
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDetailsRequest'
  /link-token:
    post:
      operationId: create
      summary: Create
      description: Creates a link token to be used when linking a new end user. The link token expires after single use.
      tags:
      - subpackage_linkToken
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDetailsRequest'
  /crm/v1/link-token:
    post:
      operationId: create
      summary: Create
      description: Creates a link token to be used when linking a new end user. The link token expires after single use.
      tags:
      - subpackage_linkToken
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDetailsRequest'
  /filestorage/v1/link-token:
    post:
      operationId: create
      summary: Create
      description: Creates a link token to be used when linking a new end user. The link token expires after single use.
      tags:
      - subpackage_linkToken
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDetailsRequest'
  /hris/v1/link-token:
    post:
      operationId: create
      summary: Create
      description: Creates a link token to be used when linking a new end user. The link token expires after single use.
      tags:
      - subpackage_linkToken
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDetailsRequest'
  /knowledgebase/v1/link-token:
    post:
      operationId: create
      summary: Create
      description: Creates a link token to be used when linking a new end user.
      tags:
      - subpackage_linkToken
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDetailsRequest_2'
  /ticketing/v1/link-token:
    post:
      operationId: create
      summary: Create
      description: Creates a link token to be used when linking a new end user. The link token expires after single use.
      tags:
      - subpackage_linkToken
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserDetailsRequest'
components:
  schemas:
    ModelPermissionDeserializerRequest:
      type: object
      properties:
        is_enabled:
          type: boolean
      title: ModelPermissionDeserializerRequest
    FieldPermissionDeserializerRequest:
      type: object
      properties:
        enabled_fields:
          type: array
          items:
            description: Any type
        disabled_fields:
          type: array
          items:
            description: Any type
      title: FieldPermissionDeserializerRequest
    LanguageEnum:
      type: string
      enum:
      - en
      - de
      title: LanguageEnum
    LanguageEnum_2:
      type: string
      enum:
      - en
      - de
      description: '* `en` - en

        * `de` - de'
      title: LanguageEnum
    CompletedAccountInitialScreenEnum:
      type: string
      enum:
      - SELECTIVE_SYNC
      title: CompletedAccountInitialScreenEnum
    LinkToken:
      type: object
      properties:
        link_token:
          type: string
        integration_name:
          type: string
        magic_link_url:
          type: string
      required:
      - link_token
      title: LinkToken
    EndUserDetailsRequest_2:
      type: object
      properties:
        end_user_email_address:
          type: string
          description: Your end user's email address. This is purely for identification purposes - setting this value will not cause any emails to be sent.
        end_user_organization_name:
          type: string
          description: Your end user's organization.
        end_user_origin_id:
          type: string
          description: This unique identifier typically represents the ID for your end user in your product's database. This value must be distinct from other Linked Accounts' unique identifiers.
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoriesEnum_2'
          description: The integration categories to show in Merge Link.
        integration:
          type:
          - string
          - 'null'
          description: The slug of a specific pre-selected integration for this linking flow token. For examples of slugs, see https://docs.merge.dev/guides/merge-link/single-integration/.
        link_expiry_mins:
          type: integer
          default: 30
          description: An integer number of minutes between [30, 720 or 10080 if for a Magic Link URL] for how long this token is valid. Defaults to 30.
        should_create_magic_link_url:
          type:
          - boolean
          - 'null'
          default: false
          description: Whether to generate a Magic Link URL. Defaults to false. For more information on Magic Link, see https://merge.dev/blog/integrations-fast-say-hello-to-magic-link.
        hide_admin_magic_link:
          type:
          - boolean
          - 'null'
          default: false
          description: Whether to generate a Magic Link URL on the Admin Needed screen during the linking flow. Defaults to false. For more information on Magic Link, see https://merge.dev/blog/integrations-fast-say-hello-to-magic-link.
        common_models:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CommonModelScopesBodyRequest'
          description: An array of objects to specify the models and fields that will be disabled for a given Linked Account. Each object uses model_id, enabled_actions, and disabled_fields to specify the model, method, and fields that are scoped for a given Linked Account.
        category_common_model_scopes:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/IndividualCommonModelScopeDeserializerRequest'
          description: When creating a Link Token, you can set permissions for Common Models that will apply to the account that is going to be linked. Any model or field not specified in link token payload will default to existing settings.
        language:
          oneOf:
          - $ref: '#/components/schemas/LanguageEnum_2'
          - type: 'null'
          description: 'The following subset of IETF language tags can be used to configure localization.


            * `en` - en

            * `de` - de'
        are_syncs_disabled:
          type:
          - boolean
          - 'null'
          default: false
          description: The boolean that indicates whether initial, periodic, and force syncs will be disabled.
        integration_specific_config:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
          description: A JSON object containing integration-specific configuration options.
        completed_account_initial_screen:
          oneOf:
          - $ref: '#/components/schemas/CompletedAccountInitialScreenEnum_2'
          - type: 'null'
          description: 'When creating a Link token, you can specifiy the initial screen of Linking Flow for a completed Linked Account.


            * `SELECTIVE_SYNC` - SELECTIVE_SYNC'
        linked_destination_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The UUID of the linked destination that you want this Linked Account to be tied to.
        credential_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The id of the credential that you want this Linked Account to be tied to.
      required:
      - end_user_email_address
      - end_user_organization_name
      - end_user_origin_id
      - categories
      title: EndUserDetailsRequest
    IndividualCommonModelScopeDeserializerRequest:
      type: object
      properties:
        model_name:
          type: string
        model_permissions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelPermissionDeserializerRequest'
        field_permissions:
          $ref: '#/components/schemas/FieldPermissionDeserializerRequest'
      required:
      - model_name
      title: IndividualCommonModelScopeDeserializerRequest
    EnabledActionsEnum:
      type: string
      enum:
      - READ
      - WRITE
      title: EnabledActionsEnum
    EndUserDetailsRequest:
      type: object
      properties:
        end_user_email_address:
          type: string
          description: Your end user's email address. This is purely for identification purposes - setting this value will not cause any emails to be sent.
        end_user_organization_name:
          type: string
          description: Your end user's organization.
        end_user_origin_id:
          type: string
          description: This unique identifier typically represents the ID for your end user in your product's database. This value must be distinct from other Linked Accounts' unique identifiers.
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoriesEnum'
          description: The integration categories to show in Merge Link.
        integration:
          type:
          - string
          - 'null'
          description: The slug of a specific pre-selected integration for this linking flow token. For examples of slugs, see https://docs.merge.dev/guides/merge-link/single-integration/.
        link_expiry_mins:
          type: integer
          default: 30
          description: An integer number of minutes between [30, 720 or 10080 if for a Magic Link URL] for how long this token is valid. Defaults to 30.
        should_create_magic_link_url:
          type:
          - boolean
          - 'null'
          default: false
          description: Whether to generate a Magic Link URL. Defaults to false. For more information on Magic Link, see https://merge.dev/blog/integrations-fast-say-hello-to-magic-link.
        hide_admin_magic_link:
          type:
          - boolean
          - 'null'
          default: false
          description: Whether to generate a Magic Link URL on the Admin Needed screen during the linking flow. Defaults to false. For more information on Magic Link, see https://merge.dev/blog/integrations-fast-say-hello-to-magic-link.
        common_models:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CommonModelScopesBodyRequest'
          description: An array of objects to specify the models and fields that will be disabled for a given Linked Account. Each object uses model_id, enabled_actions, and disabled_fields to specify the model, method, and fields that are scoped for a given Linked Account.
        category_common_model_scopes:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/IndividualCommonModelScopeDeserializerRequest'
          description: When creating a Link Token, you can set permissions for Common Models that will apply to the account that is going to be linked. Any model or field not specified in link token payload will default to existing settings.
        language:
          oneOf:
          - $ref: '#/components/schemas/LanguageEnum'
          - type: 'null'
          description: The following subset of IETF language tags can be used to configure localization.
        are_syncs_disabled:
          type:
          - boolean
          - 'null'
          default: false
          description: The boolean that indicates whether initial, periodic, and force syncs will be disabled.
        integration_specific_config:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
          description: A JSON object containing integration-specific configuration options.
        completed_account_initial_screen:
          oneOf:
          - $ref: '#/components/schemas/CompletedAccountInitialScreenEnum'
          - type: 'null'
          description: When creating a Link token, you can specifiy the initial screen of Linking Flow for a completed Linked Account.
        linked_destination_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The UUID of the linked destination that you want this Linked Account to be tied to.
        credential_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The id of the credential that you want this Linked Account to be tied to.
        ekm_enabled:
          type: boolean
          default: false
          description: Whether to enable EKM (External Key Management) for this Linked Account.
      required:
      - end_user_email_address
      - end_user_organization_name
      - end_user_origin_id
      - categories
      title: EndUserDetailsRequest
    CategoriesEnum:
      type: string
      enum:
      - hris
      - ats
      - accounting
      - ticketing
      - crm
      - mktg
      - filestorage
      - knowledgebase
      title: CategoriesEnum
    linkToken_createForRegisteredUser_Response_201:
      type: object
      properties:
        link_token:
          type: string
        magic_link_url:
          type: string
          description: URL that opens a hosted authentication page. Share this with the user so they can connect their account in a browser.
      title: linkToken_createForRegisteredUser_Response_201
    CategoriesEnum_2:
      type: string
      enum:
      - hris
      - ats
      - accounting
      - ticketing
      - crm
      - mktg
      - filestorage
      - knowledgebase
      description: '* `hris` - hris

        * `ats` - ats

        * `accounting` - accounting

        * `ticketing` - ticketing

        * `crm` - crm

        * `mktg` - mktg

        * `filestorage` - filestorage

        * `knowledgebase` - knowledgebase'
      title: CategoriesEnum
    CommonModelScopesBodyRequest:
      type: object
      properties:
        model_id:
          type: string
        enabled_actions:
          type: array
          items:
            $ref: '#/components/schemas/EnabledActionsEnum'
        disabled_fields:
          type: array
          items:
            type: string
      required:
      - model_id
      - enabled_actions
      - disabled_fields
      title: CommonModelScopesBodyRequest
    CompletedAccountInitialScreenEnum_2:
      type: string
      enum:
      - SELECTIVE_SYNC
      description: '* `SELECTIVE_SYNC` - SELECTIVE_SYNC'
      title: CompletedAccountInitialScreenEnum
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      description: Token-based authentication with required prefix "Bearer"