HEherondata
Transactions

GET /api/transactions

Changed on

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

Request

  • Base URL
    https://app.herondata.io
  • URL
    https://app.herondata.io/api/transactions
  • Auth
    API key in header x-api-key

Query parameters

from_datestring date

Deprecated; see created_date_ or timestamp_date_

to_datestring date

Deprecated; see created_date_ or timestamp_date_

created_date_minstring date
Example:2020-04-27

Filter by earliest transaction upload date - when Heron received the transaction

created_date_maxstring date
Example:2020-04-27

Filter by latest transaction upload date - when Heron received the transaction

last_updated_minstring date-time
Example:2026-11-03T15:16:37.457722

Filter for transactions whose values were last updated in Heron systems after the specified input value

last_updated_maxstring date-time
Example:2026-11-03T15:16:37.457737

Filter for transactions whose values were last updated in Heron systems before the specified input value

timestamp_date_minstring date
Example:2020-04-27

Filter by earliest transaction timestamp

timestamp_date_maxstring date
Example:2020-04-27

Filter by latest transaction timestamp

category_heron_idstring[] nullable

Filter by the heron_id of the category that the transaction is annotated with

request_idstring

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.

reference_idstring

Reference Id of transaction

heron_idstring
Example:txn_NPKoXAK2atAzxzgJQUqp7f

Heron generated Id of transaction

heron_idsstring[]

Filter to a specific set of transactions by Heron ID, e.g. the transactions an attribute cites

end_user_idstring

End user id of transaction

include_duplicatesboolean

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.

transaction_codestring

Filter by transaction code

is_recurringboolean

Filter by whether the transaction is recurring

is_payment_processingboolean

Filter by the recorded payment-processing flag. False includes transactions not yet evaluated.

has_matching_transactionboolean

Filter by whether the transaction has a matching transaction

description_keywordstring

Filter by keyword match on transaction description; case insensitive

counterparty_keywordstring

Filter by keyword match on transaction counterparty; case insensitive

description_regexstring

Filter by regex matching transaction description

min_amountnumber

Filter by minimum amount of transaction

max_amountnumber

Filter by maximum amount of transaction

min_balancenumber

Filter by minimum running balance

max_balancenumber

Filter by maximum running balance

confidence_minnumber

Filter by minimum confidence of annotation associated with transaction

confidence_maxnumber

Filter by maximum confidence of annotation associated with transaction

merchant_group_idstring

Filter by merchant group id

merchant_heron_idstring

Filter by merchant heron id

data_source_heron_idstring

Filter by data source Heron ID

merchant_namestring

Filter by keyword match on merchant name; case insensitive

has_merchantboolean nullable

Filter by whether the transaction has a merchant entity associated with it

order_by'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'

What to order transactions by

pageinteger

Page of transaction to return

limitinteger

Number of transactions to return per page

account_idsstring[] nullable

Account ids to include. If not provided, all accounts are included

[
  "1234"
]

Response

OK

Example response

{
  "transactions": [
    {
      "account_id": "checking_account_202348",
      "account_number": "1234567890",
      "amount": -42.42,
      "balance": 423,
      "categories": [
        {
          "annotator": "predicted",
          "confidence": 0.5,
          "heron_id": "ctg_fSjC3oqLGbPX7rRLvqRgn9",
          "label": "Rent",
          "model_version": "6a921325-76fb-4dcf-8a3d-062984b937f9"
        }
      ],
      "counterparty": "GOOGLE",
      "created": "2026-11-03T15:16:37.457183",
      "currency": "USD",
      "data_source_account_heron_id": "dsa_nyKpgb6VuMgZoDbqq3iWjo",
      "data_source_heron_id": "dso_mjLrdRNvZjLv4pnoTpaS42",
      "description": "GOOGLE *ADS12340929 cc@google.com US",
      "description_clean": "GOOGLE ADS",
      "duplicate_of_id": "txn_nMHguAp6nqtBNUXA2b47tg",
      "end_user_id": "my_best_customer_203948",
      "file_class": "bank_statement",
      "heron_id": "txn_MAQAVNGKMg6bWhDWRdwfFj",
      "last_updated": "2026-11-03T15:16:37.457204",
      "merchant": {
        "categories": [
          {
            "code": "7311",
            "description": "Advertising services",
            "slug": "advertising_services"
          }
        ],
        "heron_id": "mrc_irammkhfKGGy9WBesbp4sk"
      },
      "payment_processor": {
        "heron_id": "mrc_nRYdGU7nYuevb7qem65cEb",
        "icon_url": "https://storage.googleapis.com/heron-merchant-assets/icons/mrc_nRYdGU7nYuevb7qem65cEb.svg",
        "logo_url": "https://storage.googleapis.com/heron-merchant-assets/logos/mrc_nRYdGU7nYuevb7qem65cEb.svg",
        "name": "Paypal",
        "url": "https://www.paypal.com"
      },
      "reference_id": "my_favourite_transaction_231098",
      "request_id": "req_Gncyxk6tRdsWH7vQRiEutj",
      "timestamp": "2021-11-12T10:38:05Z",
      "transaction_code": "card"
    }
  ]
}

Changes

  • bd8008e49534Revision changes
    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • warning

      added the new debt.collections.mca enum value to the /////// response property for the response status

    • info

      added the new optional query request parameter data_source_heron_id

    • info

      added the new optional query request parameter heron_ids

    • info

      added the new optional query request parameter is_payment_processing

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status