openapi: 3.0.3
info:
  title: Teller Accounts Transactions API
  description: Teller is a unified banking API providing real-time access to bank accounts, transactions, balances, identity data, and payment initiation across US financial institutions. Connect to thousands of banks and credit unions through a single integration. Teller uses mutual TLS (mTLS) for application authentication and access tokens obtained via Teller Connect for per-account authorization.
  version: 2020-10-12
  contact:
    name: Teller Developer Support
    url: https://teller.io/docs
  termsOfService: https://teller.io/legal/terms-of-service
servers:
- url: https://api.teller.io
  description: Teller Production API
tags:
- name: Transactions
  description: Account transaction history
paths:
  /accounts/{account_id}/transactions:
    get:
      operationId: listTransactions
      summary: List Transactions
      description: Returns a list of all transactions belonging to the specified account. Supports pagination and date range filtering.
      tags:
      - Transactions
      security:
      - BearerMtls: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
        description: The account identifier.
      - name: count
        in: query
        schema:
          type: integer
        description: Maximum number of transactions to return.
      - name: from_id
        in: query
        schema:
          type: string
        description: Paginate backward from this transaction ID.
      - name: start_date
        in: query
        schema:
          type: string
          format: date
        description: Filter transactions on or after this ISO 8601 date.
      - name: end_date
        in: query
        schema:
          type: string
          format: date
        description: Filter transactions on or before this ISO 8601 date.
      responses:
        '200':
          description: Transactions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
        '429':
          description: Rate limit exceeded
  /accounts/{account_id}/transactions/{transaction_id}:
    get:
      operationId: getTransaction
      summary: Get Transaction
      description: Retrieve a single transaction by ID.
      tags:
      - Transactions
      security:
      - BearerMtls: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
        description: The account identifier.
      - name: transaction_id
        in: path
        required: true
        schema:
          type: string
        description: The transaction identifier.
      responses:
        '200':
          description: Transaction retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          description: Unauthorized
        '404':
          description: Transaction not found
components:
  schemas:
    TransactionDetails:
      type: object
      properties:
        processing_status:
          type: string
          enum:
          - pending
          - complete
        category:
          type: string
          description: Transaction category (e.g. dining, groceries, utilities, travel, entertainment)
        counterparty:
          type: object
          properties:
            name:
              type: string
              description: Name of the merchant or counterparty
            type:
              type: string
              enum:
              - person
              - organization
    Transaction:
      type: object
      description: A financial transaction on a bank account
      properties:
        id:
          type: string
          description: Teller transaction identifier
        account_id:
          type: string
          description: Account this transaction belongs to
        amount:
          type: string
          description: Transaction amount as signed decimal string (negative = debit)
        date:
          type: string
          format: date
          description: ISO 8601 transaction date
        description:
          type: string
          description: Bank statement text
        status:
          type: string
          enum:
          - posted
          - pending
          description: Whether the transaction has settled
        type:
          type: string
          description: Transaction type
          enum:
          - card_payment
          - transfer
          - atm
          - deposit
          - withdrawal
          - digital_payment
          - wire
          - check
          - interest
          - fee
          - other
        running_balance:
          type: string
          description: Running account balance after this transaction (posted only)
        details:
          $ref: '#/components/schemas/TransactionDetails'
        links:
          type: object
          properties:
            self:
              type: string
              format: uri
            account:
              type: string
              format: uri
  securitySchemes:
    BearerMtls:
      type: http
      scheme: bearer
      description: 'Access token obtained via Teller Connect when a user successfully enrolls their bank account. Must be used together with a Teller client certificate (mTLS). Encoded using HTTP Basic Auth scheme: ACCESS_TOKEN as username, empty password.'