openapi: 3.0.3
info:
  title: Teller Accounts 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: Accounts
  description: Bank account management
paths:
  /accounts:
    get:
      operationId: listAccounts
      summary: List Accounts
      description: Returns all bank accounts authorized by the current access token enrollment.
      tags:
      - Accounts
      security:
      - BearerMtls: []
      parameters:
      - name: Teller-Version
        in: header
        schema:
          type: string
        description: API version header.
      responses:
        '200':
          description: Accounts retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
    delete:
      operationId: deleteAccounts
      summary: Delete Accounts
      description: Removes authorization to access all accounts in the enrollment. Does not delete the actual bank accounts.
      tags:
      - Accounts
      security:
      - BearerMtls: []
      responses:
        '204':
          description: Authorization revoked for all accounts
        '401':
          description: Unauthorized
  /accounts/{account_id}:
    get:
      operationId: getAccount
      summary: Get Account
      description: Retrieve a single bank account by ID.
      tags:
      - Accounts
      security:
      - BearerMtls: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
        description: The account identifier.
      responses:
        '200':
          description: Account retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
    delete:
      operationId: deleteAccount
      summary: Delete Account
      description: Removes authorization to access the specified account. Does not delete the actual bank account.
      tags:
      - Accounts
      security:
      - BearerMtls: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
        description: The account identifier.
      responses:
        '204':
          description: Authorization revoked for account
        '401':
          description: Unauthorized
        '404':
          description: Account not found
  /accounts/{account_id}/details:
    get:
      operationId: getAccountDetails
      summary: Get Account Details
      description: Retrieve account details including routing number and account number for the specified bank account.
      tags:
      - Accounts
      security:
      - BearerMtls: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
        description: The account identifier.
      responses:
        '200':
          description: Account details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDetails'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
  /accounts/{account_id}/balances:
    get:
      operationId: getAccountBalances
      summary: Get Account Balances
      description: Retrieve current available and ledger balances for the specified account.
      tags:
      - Accounts
      security:
      - BearerMtls: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
        description: The account identifier.
      responses:
        '200':
          description: Account balances retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalances'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
components:
  schemas:
    Account:
      type: object
      description: A bank account enrolled via Teller Connect
      properties:
        id:
          type: string
          description: Teller's unique identifier for the account
        enrollment_id:
          type: string
          description: Identifier for the enrollment (user session)
        name:
          type: string
          description: Name of the account as reported by the institution
        last_four:
          type: string
          description: Last four digits of the account number
        type:
          type: string
          description: Account type
          enum:
          - checking
          - savings
          - credit_card
          - money_market
          - mortgage
          - loan
        subtype:
          type: string
          description: Account subtype
        currency:
          type: string
          description: Currency code (e.g. USD)
        status:
          type: string
          description: Account status
          enum:
          - open
          - closed
        institution:
          $ref: '#/components/schemas/InstitutionRef'
        links:
          $ref: '#/components/schemas/AccountLinks'
    AccountBalances:
      type: object
      description: Current account balance information
      properties:
        account_id:
          type: string
        available:
          type: string
          description: Available balance as a string decimal
        ledger:
          type: string
          description: Ledger/posted balance as a string decimal
        links:
          type: object
          properties:
            self:
              type: string
              format: uri
            account:
              type: string
              format: uri
    AccountDetails:
      type: object
      description: Sensitive account details including routing and account numbers
      properties:
        account_id:
          type: string
        account_number:
          type: string
          description: Full account number
        routing_numbers:
          type: object
          properties:
            ach:
              type: string
              description: ACH routing number
            wire:
              type: string
              description: Wire transfer routing number
    InstitutionRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    AccountLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
        transactions:
          type: string
          format: uri
        balances:
          type: string
          format: uri
        details:
          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.'