Get apitransactions

GET

api

transactions

curl --request GET \
  --url https://app.herondata.io/api/transactions \
  --header 'Authorization: Basic <encoded-value>'

{
  "_meta": {
    "next_url": "<string>",
    "page": 123,
    "pages": 123,
    "per_page": 123,
    "prev_url": "<string>"
  },
  "_summary": {
    "returned_transactions": 123,
    "transactions": 123
  },
  "transactions": [
    {
      "account_id": "checking_account_202348",
      "account_number": "1234567890",
      "amount": -42.42,
      "balance": 423,
      "categories": [
        {
          "annotator": "predicted",
          "confidence": 0.5,
          "heron_id": "ctg_VGwt3NNpPzjYuHfNgjuXYg",
          "label": "Rent",
          "model_version": "c087134e-98a5-4522-99fd-9bfc7470eb70"
        }
      ],
      "created": "2025-04-15T17:04:43.807566",
      "currency": "USD",
      "data_source_account_heron_id": "dsa_H8ewvz6koeQqnknaaUj8As",
      "data_source_heron_id": "dso_EAnEi6iMNt62oWDsGRYMGM",
      "description": "GOOGLE *ADS12340929 [email protected] US",
      "description_clean": "GOOGLE ADS",
      "duplicate_of_id": "<any>",
      "end_user_id": "my_best_customer_203948",
      "has_matching_transaction": true,
      "heron_id": "txn_J8wF9EogEyTSdbbpdXoGLs",
      "is_potential_duplicate": true,
      "is_recurring": true,
      "last_updated": "2025-04-15T17:04:43.807583",
      "merchant": {
        "categories": [
          {
            "code": "7311",
            "description": "Advertising services",
            "slug": "advertising_services"
          }
        ],
        "group_id": "Uber",
        "heron_id": "mrc_ifF8pnLaH9W4i4ANqaF4z3",
        "icon_url": "<string>",
        "is_priority": true,
        "logo_url": "<string>",
        "name": "<string>",
        "url": "<string>"
      },
      "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_nUKcqx7njuoVjKvghbF9je",
      "timestamp": "2021-11-12T10:38:05Z",
      "transaction_code": "card"
    }
  ]
}

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Query Parameters

is_recurring

boolean

Filter by whether the transaction is recurring

account_ids

string[] | null

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

description_keyword

string

Filter by keyword match on transaction description; case insensitive

limit

integer

default:1000

Number of transactions to return per page

Required range: 1 <= x <= 10000

merchant_group_id

string

Filter by merchant group id

description_regex

string

Filter by regex matching transaction description

include_duplicates

boolean

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_code

string

Filter by transaction code

from_date

string

Deprecated; see created_date_ or timestamp_date_

reference_id

string

Reference Id of transaction

category_heron_id

string[] | null

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

Example:

"ctg_KReKQEEfcDSzVQ4WpkmCET"

confidence_max

number

Filter by maximum confidence of annotation associated with transaction

Required range: 0 <= x <= 1

heron_id

string

Heron generated Id of transaction

Example:

"txn_8g57End49ifoa9wvw6joVE"

last_updated_max

string

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

Example:

"2025-04-15T17:04:43.807928"

max_amount

number

Filter by maximum amount of transaction

order_by

enum<string>

default:id_asc

What to order transactions by

Available options:

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

confidence_min

number

Filter by minimum confidence of annotation associated with transaction

Required range: 0 <= x <= 1

has_matching_transaction

boolean

Filter by whether the transaction has a matching transaction

request_id

string

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.

has_merchant

boolean | null

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

timestamp_date_min

string

Filter by earliest transaction timestamp

Example:

"2020-04-27"

page

integer

default:1

Page of transaction to return

Required range: x >= 1

to_date

string

Deprecated; see created_date_ or timestamp_date_

last_updated_min

string

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

Example:

"2025-04-15T17:04:43.807915"

merchant_heron_id

string

Filter by merchant heron id

created_date_max

string

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

Example:

"2020-04-27"

end_user_id

string

End user id of transaction

min_amount

number

Filter by minimum amount of transaction

created_date_min

string

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

Example:

"2020-04-27"

timestamp_date_max

string

Filter by latest transaction timestamp

Example:

"2020-04-27"

Response

200

application/json

_meta

object

_summary

object

transactions

object[]

transactions.amount

number

required

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

transactions.description

string

required

The text description for the transaction

Example:

"GOOGLE *ADS12340929 [email protected] US"

transactions.account_id

string | null

Your unique ID for account associated with transaction

Maximum length: 400

Example:

"checking_account_202348"

transactions.account_number

string

The account number associated with the transaction

Example:

"1234567890"

transactions.balance

number | null

The running balance of the account after transaction ocurred

Example:

423

transactions.categories

object[]

The category associated with the transaction

transactions.created

string

When transaction was created in Heron system

Example:

"2025-04-15T17:04:43.807566"

transactions.currency

string | null

ISO 4217 currency code

Required string length: 3

Example:

"USD"

transactions.data_source_account_heron_id

string

Unique ID of the transaction's data source account

Example:

"dsa_H8ewvz6koeQqnknaaUj8As"

transactions.data_source_heron_id

string

Unique ID of the transaction's data source

Example:

"dso_EAnEi6iMNt62oWDsGRYMGM"

transactions.description_clean

string

The cleaned description of the transaction

Example:

"GOOGLE ADS"

transactions.duplicate_of_id

any

Indicates that the transaction is a duplicate and gives the heron_id of the original

transactions.end_user_id

string | null

Your unique ID for end user associated with transaction

Maximum length: 140

Example:

"my_best_customer_203948"

transactions.has_matching_transaction

boolean

Whether the transaction is a transfer; requires end_user_id and timestamp to be present

transactions.heron_id

string

Unique ID of transaction; generated by Heron Data

Example:

"txn_J8wF9EogEyTSdbbpdXoGLs"

transactions.is_potential_duplicate

boolean

Indicates whether the transaction has another transaction similar to it

transactions.is_recurring

boolean

Whether the transaction is recurring or not; requires end_user_id and timestamp to be present

transactions.last_updated

string

When transaction was last updated in Heron system; could be from recategorisation or attribute updates

Example:

"2025-04-15T17:04:43.807583"

transactions.merchant

object

The merchant associated with the transaction

transactions.payment_processor

object

The payment processor associated with the transaction

transactions.reference_id

string | null

Your unique ID for transaction

Maximum length: 140

Example:

"my_favourite_transaction_231098"

transactions.request_id

string | null

ID associated with request, e.g., all transactions in same POST request will have same request_id

Example:

"req_nUKcqx7njuoVjKvghbF9je"

transactions.timestamp

string | null

The ISO 8601 timezone aware timestamp of the transaction; takes precedence over 'date'

Example:

"2021-11-12T10:38:05Z"

transactions.transaction_code

string | null

Code associated with transaction to indicate the type of transaction

Maximum length: 140

Example:

"card"

Was this page helpful?

Create end user transactions (async)Enrich transactions (sync)

curl --request GET \
  --url https://app.herondata.io/api/transactions \
  --header 'Authorization: Basic <encoded-value>'

{
  "_meta": {
    "next_url": "<string>",
    "page": 123,
    "pages": 123,
    "per_page": 123,
    "prev_url": "<string>"
  },
  "_summary": {
    "returned_transactions": 123,
    "transactions": 123
  },
  "transactions": [
    {
      "account_id": "checking_account_202348",
      "account_number": "1234567890",
      "amount": -42.42,
      "balance": 423,
      "categories": [
        {
          "annotator": "predicted",
          "confidence": 0.5,
          "heron_id": "ctg_VGwt3NNpPzjYuHfNgjuXYg",
          "label": "Rent",
          "model_version": "c087134e-98a5-4522-99fd-9bfc7470eb70"
        }
      ],
      "created": "2025-04-15T17:04:43.807566",
      "currency": "USD",
      "data_source_account_heron_id": "dsa_H8ewvz6koeQqnknaaUj8As",
      "data_source_heron_id": "dso_EAnEi6iMNt62oWDsGRYMGM",
      "description": "GOOGLE *ADS12340929 [email protected] US",
      "description_clean": "GOOGLE ADS",
      "duplicate_of_id": "<any>",
      "end_user_id": "my_best_customer_203948",
      "has_matching_transaction": true,
      "heron_id": "txn_J8wF9EogEyTSdbbpdXoGLs",
      "is_potential_duplicate": true,
      "is_recurring": true,
      "last_updated": "2025-04-15T17:04:43.807583",
      "merchant": {
        "categories": [
          {
            "code": "7311",
            "description": "Advertising services",
            "slug": "advertising_services"
          }
        ],
        "group_id": "Uber",
        "heron_id": "mrc_ifF8pnLaH9W4i4ANqaF4z3",
        "icon_url": "<string>",
        "is_priority": true,
        "logo_url": "<string>",
        "name": "<string>",
        "url": "<string>"
      },
      "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_nUKcqx7njuoVjKvghbF9je",
      "timestamp": "2021-11-12T10:38:05Z",
      "transaction_code": "card"
    }
  ]
}

API Reference

Categories

CrmIntegrations

EndUserDataSourceAccounts

EndUserDataSources

EmailTemplates

EndUsers

EndUserEmails

EndUserEnricherFields

EndUserEntity

EndUserFiles

FileClass

EndUserCalculations

EndUserAttributes

EnrichmentFeedback

EndUserFinancials

EndUserRules

Integrations

EndUserIntegrations

ISOApplication

EndUserAccounts

EnrichedTransactions

Transactions

Policy

Testing

Merchants

Rules

ParsedEndUserSubmission

Users

Webhooks

Get apitransactions

Authorizations

Query Parameters

Response