openapi: 3.1.0
info:
  title: Tink Data Enrichment API
  description: >
    Tink Data Enrichment categorises raw bank transactions, identifies the
    merchant, detects recurring transactions, and predicts future recurring
    payments. Provides the categorisation taxonomy and recurring-group
    rollups that power Money Manager, Expense Check, and Income Check.
  version: '1.0'
  contact:
    name: Tink Developer Support
    url: https://docs.tink.com/resources/data-enrichment
servers:
  - url: https://api.tink.com
    description: Tink EU Production
  - url: https://api.us.tink.com
    description: Tink US Production
security:
  - BearerAuth: []
tags:
  - name: EnrichedTransactions
    description: Categorised and merchant-enriched transactions.
  - name: Categories
    description: Tink categorisation taxonomy.
  - name: RecurringTransactions
    description: Recurring transaction detection and prediction.
paths:
  /enrichment/v1/transactions:
    get:
      summary: Tink List Enriched Transactions
      description: List user transactions enriched with Tink category, merchant information, and recurring flag.
      operationId: listEnrichedTransactions
      tags:
        - EnrichedTransactions
      parameters:
        - in: query
          name: accountIdIn
          schema:
            type: string
        - in: query
          name: bookedDateGte
          schema:
            type: string
            format: date
        - in: query
          name: bookedDateLte
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Enriched transactions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichedTransactionList'
  /enrichment/v1/categories:
    get:
      summary: Tink List Categories
      description: List the Tink categorisation taxonomy for the calling locale.
      operationId: listCategories
      tags:
        - Categories
      parameters:
        - in: query
          name: locale
          schema:
            type: string
      responses:
        '200':
          description: Categories returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryList'
  /enrichment/v1/recurring-transactions:
    get:
      summary: Tink List Recurring Transactions
      description: List confirmed recurring transactions (subscriptions, salary, rent) for the user.
      operationId: listRecurringTransactions
      tags:
        - RecurringTransactions
      responses:
        '200':
          description: Recurring transactions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringTransactionList'
  /enrichment/v1/predicted-recurring-transactions:
    get:
      summary: Tink List Predicted Recurring Transactions
      description: List predicted future recurring transactions inferred from the user's transaction history.
      operationId: listPredictedRecurringTransactions
      tags:
        - RecurringTransactions
      responses:
        '200':
          description: Predicted recurring transactions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringTransactionList'
  /enrichment/v1/recurring-transactions-groups:
    get:
      summary: Tink List Recurring Transaction Groups
      description: List recurring transaction groups (clusters of related recurring transactions).
      operationId: listRecurringTransactionsGroups
      tags:
        - RecurringTransactions
      responses:
        '200':
          description: Groups returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringTransactionGroupList'
  /enrichment/v1/recurring-transactions-groups/{groupId}:
    get:
      summary: Tink Get A Recurring Transaction Group
      description: Retrieve a single recurring transaction group by id.
      operationId: getRecurringTransactionsGroup
      tags:
        - RecurringTransactions
      parameters:
        - in: path
          name: groupId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Group returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringTransactionGroup'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    EnrichedTransactionList:
      type: object
      properties:
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedTransaction'
        nextPageToken:
          type: string
    EnrichedTransaction:
      type: object
      properties:
        id:
          type: string
        accountId:
          type: string
        amount:
          type: object
          properties:
            value:
              type: string
            currencyCode:
              type: string
        descriptions:
          type: object
          properties:
            original:
              type: string
            display:
              type: string
        categories:
          type: object
          properties:
            pfm:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
        merchantInformation:
          type: object
          properties:
            merchantName:
              type: string
            merchantCategoryCode:
              type: string
        recurring:
          type: boolean
        dates:
          type: object
          properties:
            booked:
              type: string
              format: date
    CategoryList:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
    Category:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        name:
          type: string
        parentId:
          type: string
        type:
          type: string
          enum: [EXPENSES, INCOME, TRANSFERS]
    RecurringTransactionList:
      type: object
      properties:
        recurringTransactions:
          type: array
          items:
            $ref: '#/components/schemas/RecurringTransaction'
    RecurringTransaction:
      type: object
      properties:
        id:
          type: string
        merchantName:
          type: string
        cadence:
          type: string
          enum: [DAILY, WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, YEARLY, IRREGULAR]
        averageAmount:
          type: object
          properties:
            value:
              type: string
            currencyCode:
              type: string
        category:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        lastOccurrence:
          type: string
          format: date
        nextExpectedOccurrence:
          type: string
          format: date
    RecurringTransactionGroupList:
      type: object
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/RecurringTransactionGroup'
    RecurringTransactionGroup:
      type: object
      properties:
        id:
          type: string
        merchantName:
          type: string
        cadence:
          type: string
          enum: [DAILY, WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, YEARLY, IRREGULAR]
        recurringTransactionIds:
          type: array
          items:
            type: string
        totalAmount:
          type: object
          properties:
            value:
              type: string
            currencyCode:
              type: string
    Error:
      type: object
      properties:
        errorMessage:
          type: string
        errorCode:
          type: string