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

# Get apitransactions

> Get transactions. At least `end_user_id`, `heron_id` or `request_id` must be provided.



## OpenAPI

````yaml https://app.herondata.io/swagger get /api/transactions
openapi: 3.0.0
info:
  contact:
    email: support@herondata.io
    name: Support
  title: Heron Data API
  version: '2021-07-19'
servers:
  - description: Production
    url: https://app.herondata.io
security:
  - ApiKeyAuth:
      - key_XXX
externalDocs:
  description: Read Tutorial
  url: https://docs.herondata.io/
paths:
  /api/transactions:
    get:
      tags:
        - Transactions
      description: >-
        Get transactions. At least `end_user_id`, `heron_id` or `request_id`
        must be provided.
      parameters:
        - description: Deprecated; see created_date_ or timestamp_date_
          in: query
          name: from_date
          required: false
          schema:
            format: date
            type: string
        - description: Deprecated; see created_date_ or timestamp_date_
          in: query
          name: to_date
          required: false
          schema:
            format: date
            type: string
        - description: >-
            Filter by earliest transaction upload date - when Heron received the
            transaction
          in: query
          name: created_date_min
          required: false
          schema:
            example: '2020-04-27'
            format: date
            type: string
        - description: >-
            Filter by latest transaction upload date - when Heron received the
            transaction
          in: query
          name: created_date_max
          required: false
          schema:
            example: '2020-04-27'
            format: date
            type: string
        - description: >-
            Filter for transactions whose values were last updated in Heron
            systems after the specified input value
          in: query
          name: last_updated_min
          required: false
          schema:
            example: '2026-07-11T16:08:47.052832'
            format: date-time
            type: string
        - description: >-
            Filter for transactions whose values were last updated in Heron
            systems before the specified input value
          in: query
          name: last_updated_max
          required: false
          schema:
            example: '2026-07-11T16:08:47.052847'
            format: date-time
            type: string
        - description: Filter by earliest transaction timestamp
          in: query
          name: timestamp_date_min
          required: false
          schema:
            example: '2020-04-27'
            format: date
            type: string
        - description: Filter by latest transaction timestamp
          in: query
          name: timestamp_date_max
          required: false
          schema:
            example: '2020-04-27'
            format: date
            type: string
        - description: >-
            Filter by the heron_id of the category that the transaction is
            annotated with
          explode: true
          in: query
          name: category_heron_id
          required: false
          schema:
            default: []
            example: ctg_avxWZPEhXGmrFfGMfuML8b
            items:
              type: string
            nullable: true
            type: array
          style: form
        - description: >-
            Request-Id header returned in the response of POST transactions.
            Sending this parameter will return all transactions sent in a
            particular POST request, including any duplicates.
          in: query
          name: request_id
          required: false
          schema:
            type: string
        - description: Reference Id of transaction
          in: query
          name: reference_id
          required: false
          schema:
            type: string
        - description: Heron generated Id of transaction
          in: query
          name: heron_id
          required: false
          schema:
            example: txn_MTsNo39VGa3VBoKYYevPdm
            type: string
        - description: End user id of transaction
          in: query
          name: end_user_id
          required: false
          schema:
            type: string
        - description: >-
            Whether or not to include duplicate transactions in the response.
            Defaults to false unless request_id is provided, in which case it
            defaults to true.
          in: query
          name: include_duplicates
          required: false
          schema:
            type: boolean
        - description: Filter by transaction code
          in: query
          name: transaction_code
          required: false
          schema:
            type: string
        - description: Filter by whether the transaction is recurring
          in: query
          name: is_recurring
          required: false
          schema:
            type: boolean
        - description: Filter by whether the transaction has a matching transaction
          in: query
          name: has_matching_transaction
          required: false
          schema:
            type: boolean
        - description: Filter by keyword match on transaction description; case insensitive
          in: query
          name: description_keyword
          required: false
          schema:
            type: string
        - description: >-
            Filter by keyword match on transaction counterparty; case
            insensitive
          in: query
          name: counterparty_keyword
          required: false
          schema:
            type: string
        - description: Filter by regex matching transaction description
          in: query
          name: description_regex
          required: false
          schema:
            type: string
        - description: Filter by minimum amount of transaction
          in: query
          name: min_amount
          required: false
          schema:
            type: number
        - description: Filter by maximum amount of transaction
          in: query
          name: max_amount
          required: false
          schema:
            type: number
        - description: Filter by minimum running balance
          in: query
          name: min_balance
          required: false
          schema:
            type: number
        - description: Filter by maximum running balance
          in: query
          name: max_balance
          required: false
          schema:
            type: number
        - description: >-
            Filter by minimum confidence of annotation associated with
            transaction
          in: query
          name: confidence_min
          required: false
          schema:
            maximum: 1
            minimum: 0
            type: number
        - description: >-
            Filter by maximum confidence of annotation associated with
            transaction
          in: query
          name: confidence_max
          required: false
          schema:
            maximum: 1
            minimum: 0
            type: number
        - description: Filter by merchant group id
          in: query
          name: merchant_group_id
          required: false
          schema:
            type: string
        - description: Filter by merchant heron id
          in: query
          name: merchant_heron_id
          required: false
          schema:
            type: string
        - description: Filter by keyword match on merchant name; case insensitive
          in: query
          name: merchant_name
          required: false
          schema:
            type: string
        - description: >-
            Filter by whether the transaction has a merchant entity associated
            with it
          in: query
          name: has_merchant
          required: false
          schema:
            nullable: true
            type: boolean
        - description: What to order transactions by
          in: query
          name: order_by
          required: false
          schema:
            default: id_asc
            enum:
              - amount_asc
              - amount_desc
              - abs_amount_asc
              - abs_amount_desc
              - description_asc
              - description_desc
              - timestamp_asc
              - timestamp_desc
              - id_asc
              - id_desc
              - confidence_asc
              - confidence_desc
              - created_asc
              - created_desc
              - balance_asc
              - balance_desc
            type: string
        - description: Page of transaction to return
          in: query
          name: page
          required: false
          schema:
            default: 1
            minimum: 1
            type: integer
        - description: Number of transactions to return per page
          in: query
          name: limit
          required: false
          schema:
            default: 1000
            maximum: 10000
            minimum: 1
            type: integer
        - description: Account ids to include. If not provided, all accounts are included
          explode: true
          in: query
          name: account_ids
          required: false
          schema:
            items:
              example: '1234'
              type: string
            nullable: true
            type: array
          style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  _meta:
                    properties:
                      next_url:
                        type: string
                      page:
                        type: integer
                      pages:
                        type: integer
                      per_page:
                        type: integer
                      prev_url:
                        type: string
                    type: object
                  _summary:
                    properties:
                      returned_transactions:
                        type: integer
                      transactions:
                        type: integer
                    type: object
                  transactions:
                    items:
                      $ref: '#/components/schemas/TransactionGetOutput'
                    type: array
                type: object
          description: OK
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TransactionGetOutput:
      properties:
        account_id:
          description: Your unique ID for account associated with transaction
          example: checking_account_202348
          maxLength: 400
          nullable: true
          type: string
        account_number:
          description: The account number associated with the transaction
          example: '1234567890'
          type: string
        amount:
          description: >-
            Amount. Inflows to an account should be positive, and outflows from
            an account should be negative. If using Plaid, please flip the
            amount sign for all transactions.
          example: -42.42
          type: number
        balance:
          description: The running balance of the account after transaction ocurred
          example: 423
          nullable: true
          type: number
        categories:
          description: The category associated with the transaction
          items:
            $ref: '#/components/schemas/TransactionAnnotation'
          type: array
        counterparty:
          description: The counterparty associated with the transaction, if available
          example: GOOGLE
          nullable: true
          type: string
        created:
          description: When transaction was created in Heron system
          example: '2026-07-11T16:08:47.052299'
          format: date-time
          type: string
        currency:
          description: ISO 4217 currency code
          example: USD
          maxLength: 3
          minLength: 3
          nullable: true
          type: string
        data_source_account_heron_id:
          description: Unique ID of the transaction's data source account
          example: dsa_6igJiWx857Ds9jeQZQ76nb
          readOnly: true
          type: string
        data_source_heron_id:
          description: Unique ID of the transaction's data source
          example: dso_Ncwc9j5KQUr9bQ8aRCCUx5
          readOnly: true
          type: string
        description:
          description: The text description for the transaction
          example: GOOGLE *ADS12340929 cc@google.com US
          type: string
        description_clean:
          description: The cleaned description of the transaction
          example: GOOGLE ADS
          type: string
        duplicate_of_id:
          description: >-
            Indicates that the transaction is a duplicate and gives the heron_id
            of the original
          example: txn_bS8spe2h5UpfXVkQxx3w44
        end_user_id:
          description: Your unique ID for end user associated with transaction
          example: my_best_customer_203948
          maxLength: 140
          nullable: true
          type: string
        has_matching_transaction:
          description: >-
            Whether the transaction is a transfer; requires end_user_id and
            timestamp to be present
          type: boolean
        heron_id:
          description: Unique ID of transaction; generated by Heron Data
          example: txn_ESjs3xSmh6C86u8xCE2seR
          readOnly: true
          type: string
        is_potential_duplicate:
          description: >-
            Indicates whether the transaction has another transaction similar to
            it
          readOnly: true
          type: boolean
        is_recurring:
          description: >-
            Whether the transaction is recurring or not; requires end_user_id
            and timestamp to be present
          type: boolean
        last_updated:
          description: >-
            When transaction was last updated in Heron system; could be from
            recategorisation or attribute updates
          example: '2026-07-11T16:08:47.052329'
          format: date-time
          type: string
        mcc_code:
          description: >-
            Merchant category code associated with transaction that you may have
            received from other sources
          nullable: true
          pattern: ^\d{4}$
          type: string
          writeOnly: true
        merchant:
          allOf:
            - $ref: '#/components/schemas/Merchant'
          description: The merchant associated with the transaction
        order:
          description: >-
            If sending a batch of transactions, the order in which the
            transaction occurs, where a higher value is equivalent to a more
            recent transaction
          nullable: true
          type: integer
          writeOnly: true
        payment_processor:
          allOf:
            - $ref: '#/components/schemas/PaymentProcessor'
          description: The payment processor associated with the transaction
        reference_id:
          description: Your unique ID for transaction
          example: my_favourite_transaction_231098
          maxLength: 140
          minLength: 1
          nullable: true
          type: string
        request_id:
          description: >-
            ID associated with request, e.g., all transactions in same POST
            request will have same request_id
          example: req_iwQyYCnHdBujtGetkCt22o
          nullable: true
          readOnly: true
          type: string
        timestamp:
          description: >-
            The ISO 8601 timezone aware timestamp of the transaction; takes
            precedence over 'date'
          example: '2021-11-12T10:38:05Z'
          format: date-time
          nullable: true
          type: string
        transaction_code:
          description: Code associated with transaction to indicate the type of transaction
          example: card
          maxLength: 140
          nullable: true
          type: string
      required:
        - amount
        - description
      type: object
    TransactionAnnotation:
      properties:
        annotator:
          description: Annotator type
          example: predicted
          type: string
        confidence:
          description: The confidence associated with the category annotation
          example: 0.5
          type: number
        heron_id:
          description: Unique ID of category; generated by Heron Data
          example: ctg_YVF6K8cdquXdGJCvj6oVCP
          type: string
        label:
          description: Label of category
          example: Rent
          type: string
        model_version:
          description: The model version that produced the categorisation
          example: 121d23e5-49f6-4538-bd63-b7e2593204c2
          type: string
      type: object
    Merchant:
      properties:
        categories:
          items:
            $ref: '#/components/schemas/MerchantCategory'
          readOnly: true
          type: array
        group_id:
          enum:
            - Uber
            - Google
            - Intuit
            - debt.mca_or_rbf
            - debt.non_bank_business
            - debt.equipment_and_auto_leasing
            - debt.mortgage
            - debt.personal_non_mortgage
            - debt.collections
            - debt.bank
            - invoice_factoring
            - fuel_provider
            - gambling_and_betting
            - null
          nullable: true
          type: string
        heron_id:
          example: mrc_WHu4jdZNVbYb9QHMJr2SN9
          readOnly: true
          type: string
        icon_url:
          format: url
          nullable: true
          type: string
        is_priority:
          readOnly: true
          type: boolean
        logo_url:
          format: url
          nullable: true
          type: string
        name:
          type: string
        url:
          format: url
          type: string
      required:
        - name
        - url
      type: object
    PaymentProcessor:
      properties:
        heron_id:
          example: mrc_nRYdGU7nYuevb7qem65cEb
          readOnly: true
          type: string
        icon_url:
          example: >-
            https://storage.googleapis.com/heron-merchant-assets/icons/mrc_nRYdGU7nYuevb7qem65cEb.svg
          format: url
          nullable: true
          readOnly: true
          type: string
        logo_url:
          example: >-
            https://storage.googleapis.com/heron-merchant-assets/logos/mrc_nRYdGU7nYuevb7qem65cEb.svg
          format: url
          nullable: true
          readOnly: true
          type: string
        name:
          example: Paypal
          nullable: true
          readOnly: true
          type: string
        url:
          example: https://www.paypal.com
          format: url
          nullable: true
          readOnly: true
          type: string
      type: object
    MerchantCategory:
      properties:
        code:
          example: '7311'
          readOnly: true
          type: string
        description:
          example: Advertising services
          nullable: true
          readOnly: true
          type: string
        slug:
          example: advertising_services
          nullable: true
          readOnly: true
          type: string
      required:
        - code
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````