Transactions Overview

Transactions represent any instance in which money moves into or out of an account. This could be a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, and so on. Transactions are created automatically when a member is successfully aggregated.

Each transaction belongs to only one account.

With these endpoints you can:

• List transactions by account, by member, by tag.
• List all transactions associated with a user.
• Read and update a transaction.
• (With Extended Transaction History) Access up to 24 months of data associated with a particular member for some institutions.
• Split a transaction and create two or more child transactions that are branched from a previous transaction.
• Create a manual transaction associated with a manual account.
• Delete a manual transaction, a transaction rule, or a split transaction.

Transactions Fields

Field	Data Type	Description
account_guid	String	The unique identifier for the account associated with the transaction. Defined by MX.
account_id	String	The unique partner-defined identifier for the account associated with the transaction. This can only be set for partner-managed accounts. It should be ignored for user-managed transactions, even in occasional cases where it may return with a value.
amount	Decimal	The monetary amount of the transaction.
category	String	The category of the transaction.
category_guid	String	The unique identifier for the category assigned to the transaction.
check_number_string	String	The check number for the transaction.
created_at	String	The date and time the transaction was created.
currency_code	String	The three-character ISO 4217 currency code, e.g. USD.
date	String	The date on which the transaction took place. This is the field used when searching for transactions by date. This field is generally the same as transacted_at, but uses posted_at as a fallback.
description	String	A human-readable version of the original_description field described below, for example "Grocery World," "Jim's Bar and Tavern." This is provided by the MX Platform.
guid	String	The unique identifier for the transaction. Defined by MX.
id	String	The unique partner-defined identifier for the transaction. This can only be set for partner-managed transactions. It should be ignored for user-managed transactions, even in occasional cases where it may return with a value.
is_bill_pay	Boolean	This indicates whether the transaction represents a bill pay.
is_direct_deposit	Boolean	This indicates whether the transaction represents a direct deposit.
is_expense	Boolean	This indicates whether the transaction represents an expense.
is_fee	Boolean	This indicates whether the transaction represents a fee.
is_income	Boolean	This indicates whether the transaction represents income.
is_international	Boolean	If the transaction is international as defined by the data provider, this field will be true. If the data provider determines it is not international then it will be false. It will be null if the data provider does not have this information.
is_manual	Boolean	This indicates whether the transaction is manually created and belongs to a manual account.
is_overdraft_fee	Boolean	This indicates whether the transaction represents an overdraft fee.
is_payroll_advance	Boolean	This indicates whether the transaction represents a payroll advance.
is_recurring	Boolean	This field should be ignored. If this information is required, please reach out to MX to discuss an alternative.
is_subscription	Boolean	This indicates whether the transaction represents a payment for a subscription service such as Netflix or Audible.
latitude	Decimal	The latitude of the location where the transaction occurred. The number is a signed decimal (for example Rio de Janeiro's latitude is -22.9027800 and Tokyo's latitude is 35.689488).
localized_description	String	A human-readable description of the transaction, provided in a local language.
localized_memo	String	Additional descriptive information about the transaction, provided in a local language.
longitude	Decimal	The longitude of the location where the transaction occurred. The number is a signed decimal (for example Rio de Janeiro's longitude is -43.2075000 and Tokyo's is 139.691706).
member_guid	String	The unique identifier for the member associated with the transaction Defined by MX.
member_is_managed_by_user	Boolean	This indicates whether the associated member is managed by the user or the MX partner. Members created with the managed member feature will have this field set to false.
memo	String	This field contains additional descriptive information about the transaction.
merchant_category_code	Integer	The ISO 18245 category code for the transaction.
merchant_guid	String	The unique identifier for the merchant associated with this transaction. Defined by MX.
merchant_location_guid	String	The unique identifier for the merchant_location associated with this transaction. Defined by MX.
original_description	String	The original description of the transaction as provided by our data feed. See description above for more information.
posted_at	String	The date and time the transaction was posted to the account.
status	String	The status of the transaction. This will be either POSTED or PENDING.
top_level_category	String	The parent category assigned to this transaction's category.
transacted_at	String	The date and time the transaction took place.
type	String	The type of transaction. This will be either CREDIT or DEBIT.
updated_at	String	The date and time the transaction was last updated.
user_guid	String	The unique identifier for the user associated with this transaction. Defined by MX.
user_id	String	The unique partner-defined identifier for the user associated with the transaction

Transaction Statuses

The status field may either be PENDING or POSTED.

All transaction data on our systems represent what we get through our data feed which depends on what institutions make available for aggregation.

Many institutions do not provide data for pending transactions; transactions from those accounts always have a status of POSTED.

When we do receive data for pending transactions, a single transaction may be updated from PENDING to POSTED and keep the same GUID. This is done through various matching methods performed automatically by MX.

If a single transaction can't be updated, the PENDING transaction will often be deleted and replaced with a new POSTED transaction (with a new GUID) when it is sent to us; this is the most common scenario when pending data is available.

In unusual circumstances, there may be separate PENDING and POSTED transactions on MX systems for up to 14 days. All PENDING transactions are deleted after 14 days as a failsafe.

Transaction Categories

Default Categories

Auto & Transport

Bill & Utilities

Business Services

Education

Entertainment

Fees & Charges

Financial

Food & Dining

Gifts & Donations

Health & Fitness

Home

Income

Investments

Kids

Personal Care

Pets

Shopping

Taxes

Transfer

Travel

Uncategorized

Enhanced Transactions

The Enhance Transactions endpoint, categorizes, cleanses, and classifies transactions. These transactions are not persisted or stored on the MX platform. Use this endpoint to:

• Improve customer insights by understanding spending behavior.
• Enhance transaction categorization with merchant details and classifications.
• Enable better financial forecasting through repeating transaction detection.
• Unlock more geolocation metadata

Enhanced Transaction Fields

Field	Data Type	Definition
amount	Decimal	The monetary amount of the transaction.
categorized_by	Integer	The method used to determine the category assigned to the transaction.
category	String	The category of the transaction.
category_guid	String	The unique identifier for the category assigned to the transaction.
described_by	Integer	The method used to describe the transaction.
description	String	A human-readable version of the original_description field described below, for example "Sam's Club," "Johnny's Tavern." This is provided by the MX Platform.
extended_transaction_type	String	The transaction type assigned by the partner.
id	String	The unique partner-defined identifier for the transaction.
is_bill_pay	Boolean	This indicates whether the transaction represents a bill pay.
is_direct_deposit	Boolean	This indicates whether the transaction represents a direct deposit.
is_expense	Boolean	This indicates whether the transaction represents an expense.
is_fee	Boolean	This indicates whether the transaction represents a fee.
is_income	Boolean	This indicates whether the transaction represents income.
is_international	Boolean	If the transaction is international as defined by the data provider, this field will be true. If the data provider determines it is not international then it will be false. It will be null if the data provider does not have this information.
is_overdraft_fee	Boolean	This indicates whether the transaction represents an overdraft fee.
is_payroll_advance	Boolean	This indicates whether the transaction represents a payroll advance.
is_subscription	Boolean	This indicates whether the transaction represents a payment for a subscription service such as Netflix or Audible.
memo	String	This field contains additional descriptive information about the transaction.
merchant_category_code	Integer	The ISO 18245 category code for the transaction.
merchant_guid	String	The unique identifier for the merchant associated with this transaction. Defined by MX.
merchant_location_guid	String	The unique identifier for the merchant_location associated with this transaction. Defined by MX.
original_description	String	The original description of the transaction as provided by our data feed. See description above for more information.
type	String	The type of transaction. This will be either CREDIT or DEBIT.

Optional Enhancement Query Parameter

Append the includes query parameter to fetch additional transaction metadata:

• Repeating Transactions: Identifies transactions with predictable recurrence patterns (for example Bill, Income, Subscription)
• Merchants: Enhances transactions with merchant name
• Classifications: Provides more insight into the type of money movement that is occurring on the transaction, whether it be retail or investments.
• Geolocation: Provides geographic metadata to enhance fraud detection and customer analytics (beginning with state, soon to include city, zip)

Opt-In Mechanism

These updates do not affect existing API consumers. Clients can opt in to these enhancements by appending the includes query parameter to their transaction API requests.

Examples:

• To retrieve all available enhancements, append: ?includes=repeating_transactions,merchants,classifications,geolocations
• You may also select specific enhancements. For example:
  • To request only Repeating Transactions and Geolocation data: ?includes=repeating_transactions,geolocations
  • To request only Classification data: ?includes=classifications

The appending add-on to the existing transaction endpoints can only be applied to:

• List transactions by account
• List transactions by member
• List transactions by tag
• List transactions
• Read transaction

note

• The appending add-on is format sensitive
• Clients can combine any subset of these enhancements as needed.
• These enhancements provide additional insights without modifying existing API behavior.
• The includes parameter supports future extensibility, allowing MX to introduce new optional fields without breaking compatibility.

Enhanced Endpoints Data Fields

Repeating Transactions Fields

Field	Type	Description
guid	String	Unique identifier for the repeating transaction, beginning with the prefix RPT-
repeating_transaction_type	Enum	Type of recurrence (for example BILL, SUBSCRIPTION, INCOME, UNKNOWN).
recurrence_type	Enum	The frequency at which a transaction is expected to repeat based on historical patterns. See Recurrence Types for full list.

Merchant Fields

Field	Type	Description
name	String	Name of the merchant.
guid	String	Unique identifier for the merchant, beginning with the prefix MCH-
logo_url	String	The URL for a 100px x 100px logo for the merchant.
website_url	String	The URL for the merchant's website, such as https://www.mx.com

Classification Fields

Field	Type	Description
parent_class	String	Specifies the overarching category of the money movement within the transaction. See the full list of Classification Values and definitions below.
guid	String	Unique identifier for the classification, beginning with the prefix MNC-

Classification Value

Classification values specify the overarching category of the money movement within the transaction.

Value	Description
Payroll	Payroll deposits, typically from an employer or payroll provider.
Deposit	Money incoming from outside of the user's account(s).
Savings	Identified as money transfers tied to a savings account, including automated savings transfers or manual deposits to designated savings funds.
Transfer	Funds moved between accounts owned by the same individual. This is the default classification for non-specific transfers.
Refunds	Funds are credited back to the account, usually resulting from returns, merchant reversals, or reimbursements.
Spend	Identified as expenditures, including purchases at merchants or service providers. If a transaction cannot be assigned to a specific spending category, it defaults to this classification.
Investment	Related to investment accounts that do not fall under more specific classifications such as buy, sell, income, fees, or corporate actions. This classification includes general investment transactions and portfolio adjustments.
Buy	Asset purchases within an investment account. These transactions typically indicate the acquisition of securities, stocks, ETFs, or other financial instruments.
Sell	Asset sales within an investment account, representing the liquidation of previously acquired securities.
Income	Investment-related income, such as dividends, interest payments, or capital gains distributions.
Fees, Expenses	Charges incurred within an investment account, including brokerage fees, advisor fees, and other associated expenses.
Corporate Actions	Events initiated by publicly traded companies that impact security holders, including stock splits, mergers, and dividends.
Other	Transactions that do not fall into any predefined investment classification. This may include adjustments, transfers within investment accounts, or unclassified financial events.

Geolocation Fields

Field	Type	Description
country	String	Country name.
state	String	State/Province name.
city	String	Region/city name.
postal code	String	Postal code/zip code.

Repeating Transactions

Repeating Transactions empowers you to deliver insights into recurring financial obligations (bills, subscriptions) and income streams. By identifying patterns in transaction data, your users can gain clarity on cash flow, enabling proactive budgeting and personalized financial experiences.

• Dynamic Recurrence Detection: Automatically identifies transactions occurring 3+ times using machine learning.
• Predictive Analytics: Predicts upcoming expenses and income for improved budgeting.
• Multi-Channel Integration: Access via dedicated endpoints or enriched transaction data.
• The API supports a 13-month lookback period for historical data retrieval.
• Merchant must appear in ≥50 MX transactions to be considered repeatable.

Repeating Transactions Endpoints

Available endpoints:

• List Repeating Transactions
• Get a Repeating Transaction

Repeating Transaction Fields

Field Name	Type	Description
guid	String	Unique identifier for the repeating transaction, beginning with the prefix RPT- Note: This field appears on transaction endpoints where the optional query parameter is defined.
user_guid	String	Unique identifier for the user.
account_guid	String	Associated account identifier.
description	String	Merchant or bill description.
amount	Number	Transaction amount.
last_posted_date	Date	Last occurrence date.
predicted_occurs_on	Date	Predicted next occurrence.
transaction_type	Enum	DEBIT or CREDIT.
recurrence_type	Enum	The frequency at which a transaction is expected to repeat based on historical patterns. See Supported Recurrence Types for full list Note: This field appears on transaction endpoints where the optional query parameter is defined.
repeating_transaction_type	Enum	BILL, SUBSCRIPTION, INCOME, UNKNOWN. Note: This field appears on transaction endpoints where the optional query parameter is defined.
merchant_guid	String	Identifier for the associated merchant.

Supported Recurrence Types

Recurrence Type	Description
EVERY_WEEK	The transaction occurs on a weekly basis.
EVERY_OTHER_WEEK	The transaction repeats every two weeks.
TWICE_A_MONTH	The transaction repeats twice a month.
EVERY_MONTH	The transaction occurs once a month, on or around the same date.
EVERY_OTHER_MONTH	The transaction repeats every two months.
EVERY_QUARTER	The transaction recurs every three months.
EVERY_OTHER_QUARTER	The transaction repeats every six months.
EVERY_YEAR	The transaction occurs annually on or around the same date.
UNKNOWN	The transaction is identified as recurring, but the system is unable to confidently determine a specific frequency pattern.