Transactions Overview - MX Documentation

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

Auto & Transport

Auto Insurance
Auto Payment
Gas & Fuel
Parking
Public Transportation
Ride Sharing
Service & Parts

Bills & Utilities

Gas & Electric
Internet
Mobile Phone
Phone
Television
Trash
Water

Business Services

Advertising
Legal
Office Supplies
Printing
Shipping

Education

Books & Supplies
Student Loan
Tuition

Entertainment

Arts
Movies & DVDs
Music
Newspapers & Magazines
Sports

Fees & Charges

ATM Fee
Bank Fee
Finance Charge
Late Fee
Overdraft
Service Fee
Trade Commissions

Financial

Financial Advisor
Life Insurance
Investment

Food & Dining

Alcohol & Bars
Coffee Shops
Fast Food
Groceries
Restaurants

Gifts & Donations

Charity
Gift

Health & Fitness

Dentist
Doctor
Eye Care
Gym
Health Insurance
Pharmacy
Sports

Home

Furnishings
Home Improvement
Home Insurance
Home Services
Home Supplies
Lawn & Garden
Mortgage & Rent

Income

Bonus
Interest Income
Paycheck
Reimbursement
Rental Income

Investments

Buy
Deposit
Dividend & Cap Gains
Sell
Withdrawal

Kids

Baby Supplies
Babysitter & Daycare
Child Support
Kids Activities
Toys

Personal Care

Hair
Laundry
Spa & Massage

Pets

Pet Food & Supplies
Pet Grooming
Veterinary

Shopping

Books
Clothing
Electronics & Software
Hobbies
Sporting Goods

Taxes

Federal Tax
Local Tax
Property Tax
Sales Tax
State Tax

Transfer

Credit Card Payment
Transfer

Travel

Air Travel
Hotel
Rental Car & Taxi
Vacation

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:

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

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:

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.

​Transactions Fields

​Transaction Statuses

​Transaction Categories

​Enhanced Transactions

​Enhanced Transaction Fields

​Optional Enhancement Query Parameter

​Enhanced Endpoints Data Fields

​Repeating Transactions

​Repeating Transactions Endpoints

​Repeating Transaction Fields

​Supported Recurrence Types

Transactions Fields

Transaction Statuses

Transaction Categories

Enhanced Transactions

Enhanced Transaction Fields

Optional Enhancement Query Parameter

Enhanced Endpoints Data Fields

Repeating Transactions

Repeating Transactions Endpoints

Repeating Transaction Fields

Supported Recurrence Types