> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List transactions by account
>
Requests to this endpoint return a list of transactions associated with the specified account.
Enhanced transaction data may be requested using the `includes` parameter. To use this optional parameter, the value should include the optional metadata requested such as `repeating_transactions`, `merchants`, `classifications`, `geolocations`. For more information, see the [Optional Enhancement Query Parameter guide](/api-reference/platform-api/reference/transactions#enhanced-transactions).
## OpenAPI
````yaml openapi/platform-api/v20250224.yaml GET /users/{user_guid}/accounts/{account_guid}/transactions
openapi: 3.0.0
info:
contact:
name: MX Platform API
url: https://www.mx.com/products/platform-api
description: >
The MX Platform API is a powerful, fully-featured API designed to make
aggregating and enhancing financial data easy and reliable. It can
seamlessly connect your app or website to tens of thousands of financial
institutions.
## What's Changed?
Several endpoints, headers, and fields changed in `v20250224`. For more on
breaking changes, refer to our
[versioning](/api-reference/platform-api/overview/versioning#v20250224) and
[migration](/api-reference/platform-api/overview/migration) guides.
## Version Header
Versions are set in the `Accept-Version` header of API requests. Version
numbers correspond with the date associated with that version. The example
below uses the version `v20250224`.
```
-H 'Accept: application/json'
-H 'Accept-Version: v20250224'
```
---
title: MX Platform API
version: '20250224'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: authorization
- name: accounts
description: >
The Accounts endpoints represent a user's checking, savings, mortgage,
401(k), or other types of accounts held by a financial institution.
An account belongs to a `member`, which represents the user's overall
relationship with a particular financial institution. A checking account
may be just one part of a larger relationship that could also include a
car loan and a savings account.
Accounts—and the transactions associated with them—are updated every 24
hours, unless the associated `user` is disabled.
You can also create manual accounts. Since a manual account has no
credentials tied to the member, the account will never aggregate or
include data from a data feed. All manual accounts are automatically
created under the Manual Institution member.
- name: ach return
description: >
The features documented here are in a beta state, and this documentation
is considered draft material subject to frequent change.
Using our Platform API, you can securely submit ACH Returns to reduce your
ACH return rates and automate your ACH return process.
You can query the status and outcomes of your submitted ACH returns to
track progress and access resolution details.
- name: budgets
description: >
Use these endpoints to create and manage budgets for your end users.
You can create a budget for a specific category or autogenerate a budget
for several categories based on existing transactions.
Each budget has a `category_guid`, relating to one of the
[categories](docs.mx.com/api-reference/platform-api/reference/categories#default-categories-and-subcategories).
- name: categories
description: >
A `transaction` can have its `category` set to one of MX’s default
categories or a custom category for a specific `user`.
See [Default Categories and
Subcategories](docs.mx.com/api-reference/platform-api/reference/categories#default-categories-and-subcategories)
for a complete list.
- name: deprecated
- name: goals
description: >
Use these endpoints to create and manage goals for a `user`. You can also
reposition goals to adjust their priority levels.
Every goal has a track type and a meta type.
The [track
type](docs.mx.com/api-reference/platform-api/reference/goals/#goal-track-type)
is the overall classification of the goal (debt, savings, retirement, or
emergency fund) while the [meta
type](docs.mx.com/api-reference/platform-api/reference/goals/#goal-meta-type)
is the specific classification (like college, house, vacation, and so on).
- name: insights
description: >
Use these endpoints to build customizable user experiences in UIs powered
by our Financial Insights data.
With Financial Insights, your users will receive personalized insights
based on their transaction history.
Want to learn more about the product? See [Financial
Insights](docs.mx.com/products/experience/insights).
Looking for a guide to use these endpoints? See [Build Your Own Insights
UI](docs.mx.com/products/experience/insights/integration-guides/insights-api-guide).
- name: institutions
description: >
Institutions represent a financial institution.
A single real-world financial institution may have several `institution`
objects on the MX platform.
For example, the mortgage division of a financial institution might use a
separate system than its everyday banking division, which is different
from its credit card division.
For more info, see [Institutions
Overview](docs.mx.com/api-reference/reference/institutions).
- name: investment holdings
description: >
Investment Data Enhancement lets you connect to an end user's financial
institution and retrieve cleansed and enhanced investment data. By
combining investment data with retail banking information, you get
comprehensive insights into customer financial behaviors, risk tolerance,
and investment strategies.
You can [read a user's
holding](docs.mx.com/api-reference/platform-api/reference/read-holding),
[list all their
holdings](docs.mx.com/api-reference/platform-api/reference/list-holdings),
or list their holdings by
[account](docs.mx.com/api-reference/platform-api/reference/list-holdings-by-account)
or
[member](docs.mx.com/api-reference/platform-api/reference/list-holdings-by-member).
You can also [deactivate a
user](docs.mx.com/api-reference/platform-api/reference/deactivate-user)
from the Investment Data Enhancement. This is non-billable.
- name: managed data
- name: members
description: >
Members represent the connection between an end user and a financial
institution. This institution may represent your institution or another
one from which MX is aggregating data.
For more info, see [Members
Overview](docs.mx.com/api-reference/reference/members).
- name: merchants
description: >
Merchants are representations of a transaction’s origin. For example, if
you buy a coffee at Starbucks, the transaction merchant will be
`Starbucks`.
Use the `merchant_guid` and a `merchant_location_guidon` any `transaction`
object to access Merchant endpoints for details like the merchant’s name,
logo URL, website, street address, and more.
- name: microdeposits
description: >
Microdeposits is an additional verification method that allows you to
verify account details and navigate the process of using microdeposits and
the automated clearing house (ACH) system.
Make two, small ACH deposits into a consumer's account using the provided
account and routing number. You can then require that the end user confirm
the exact amount of each deposit to verify that they own the account and
meet NACHA’s account verification.
For more info, including process flows, setting block lists, and more, see
[Microdeposits](docs.mx.com/products/connectivity/microdeposits).
- name: monthly cash flow profile
- name: notifications
description: >
You can only use notifications endpoints if you’re using the MX mobile
application.
All notifications created through the API will be of notification type
`API_NOTIFICATION`, channel `PUSH`, and will not be associated to an
entity. No other channels are supported.
The read and list endpoints can return any notification associated with
the `user`, including notifications created by MX for other channels
besides `PUSH`.
- name: processor token
- name: rewards
- name: spending plan
description: >
Use the Spending Plan endpoints to create your own version of our
[Spending Plan
Widget](docs.mx.com/products/experience/pfm/legacy-widget-overviews/spending-plan),
which helps end users track their spending throughout the month.
To understand key terms and how to best use these endpoints, see [Build
Your Own Spending Plan
UI](docs.mx.com/products/experience/pfm/integration-guides/build-your-own-spending-plan-ui).
- name: statements
description: >
With Statements, you can retrieve a user's monthly account statements in
PDF format. This data can be used for solutions like personal financial
management or risk analysis.
- name: taggings
description: >
Tags and taggings are two resources in the MX Platform API that, when used
together, give end users more control over organizing their transactions.
A tag is a custom label that can be applied to a transaction.
After you create a tag, use it for tagging. This means you should actually
apply the tag to a particular transaction.
Together, they're a powerful tool for personalization, customization, and
money management.
For a guide on creating a tag and then applying it to a specific
transaction with a tagging, see [Custom Tags and
Taggings](docs.mx.com/products/experience/pfm/integration-guides/personalization/).
- name: tags
description: >
Tags and taggings are two resources in the MX Platform API that, when used
together, give end users more control over organizing their transactions.
A tag is a custom label that can be applied to a transaction.
After you create a tag, use it for tagging. This means you should actually
apply the tag to a particular transaction.
Together, they're a powerful tool for personalization, customization, and
money management.
For a guide on creating a tag and then applying it to a specific
transaction with a tagging, see [Custom Tags and
Taggings](docs.mx.com/products/experience/pfm/integration-guides/personalization/).
- name: transaction rules
description: >
Transaction Rules allow users to automatically recategorize or rename all
similar transactions according to their preferences. This only applies to
future transactions.
When recategorizing or renaming a transaction, the user will be asked
whether they want the new data to apply to the selected transaction or to
all future transactions. If they choose to apply it to all future
transactions, it will create a transaction rule which will automatically
apply the changes going forward.
- name: transactions
description: >
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`.
For more info, see [Transactions
Overview](docs.mx.com/api-reference/reference/transactions).
- name: users
description: >
Users represent an end user using the Platform API through your web or
mobile app.
Users are created by MX clients and belong to a specific
[client](docs.mx.com/products/connectivity/overview/data-architecture/#clients)
on the platform.
- name: verifiable credentials
description: >
MX provides Verifiable Credential endpoints that comply with web5
standards.
For more info, see [Verifiable Credentials
Overview](docs.mx.com/api-reference/reference/verifiable-credentials).
- name: widgets
description: >
Use the [Request Widget
URL](docs.mx.com/api-reference/platform-api/reference/request-widget-url)
endpoint to generate a URL that loads one of our widgets.
Many request body parameters only work for some widgets.
For more info, including widget types, see [Widgets
Overview](docs.mx.com/api-reference/reference/widgets).
paths:
/users/{user_guid}/accounts/{account_guid}/transactions:
get:
tags:
- transactions
summary: List transactions by account
description: >-
Requests to this endpoint return a list of transactions associated with
the specified account.
Enhanced transaction data may be
requested using the `includes` parameter. To use this optional
parameter, the value should include the optional metadata requested
such as `repeating_transactions`, `merchants`, `classifications`,
`geolocations`. For more information, see the [Optional Enhancement
Query Parameter
guide](/api-reference/platform-api/reference/transactions-overview#enhanced-transactions#optional-enhancement-query-parameter).
operationId: listTransactionsByAccount
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/userGuid'
- $ref: '#/components/parameters/accountGuid'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPageMax1000'
- $ref: '#/components/parameters/fromDateUnix'
- $ref: '#/components/parameters/toDateUnix'
- $ref: '#/components/parameters/fromCreatedAt'
- $ref: '#/components/parameters/toCreatedAt'
- $ref: '#/components/parameters/fromUpdatedAt'
- $ref: '#/components/parameters/toUpdatedAt'
- $ref: '#/components/parameters/includes'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionsResponseBodyIncludes'
description: OK
components:
parameters:
acceptVersion:
name: Accept-Version
in: header
required: true
schema:
type: string
default: v20250224
example: v20250224
description: MX Platform API version.
userGuid:
description: The unique identifier for a `user`, beginning with the prefix `USR-`.
example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
in: path
name: user_guid
required: true
schema:
type: string
accountGuid:
description: The unique id for an `account`.
example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
in: path
name: account_guid
required: true
schema:
type: string
page:
description: Results are paginated. Specify current page.
example: 1
in: query
name: page
schema:
type: integer
recordsPerPageMax1000:
description: >-
This specifies the number of records to be returned on each page.
Defaults to `25`. The valid range is from `10` to `1000`. If the value
exceeds `1000`, the default value of `25` will be used instead.
example: 10
in: query
name: records_per_page
schema:
type: integer
fromDateUnix:
description: >-
Filter transactions from this date. This only supports unix timestamp
format. Defaults to 120 days ago if not provided.
example: '1666936800'
in: query
name: from_date
schema:
type: string
toDateUnix:
description: >-
Filter transactions to this date (at midnight). This only supports unix
timestamp format. Defaults to 5 days forward from the day the request is
made to capture pending transactions.
example: '1698472800'
in: query
name: to_date
schema:
type: string
fromCreatedAt:
name: from_created_at
in: query
description: >-
Filter transactions from the date the transaction was created. This only
supports unix timestamp format.
example: '1666936800'
schema:
type: string
toCreatedAt:
name: to_created_at
description: >-
Filter transaction to the date in which the transaction was created.
This only supports unix timestamp format.
example: '1698472800'
in: query
schema:
type: string
fromUpdatedAt:
name: from_updated_at
description: >-
Filter transactions from the date in which the transaction was updated.
This only supports unix timestamp format.
example: '1666936800'
in: query
schema:
type: string
toUpdatedAt:
name: to_updated_at
description: >-
Filter transactions to the date in which the transaction was updated.
This only supports unix timestamp format.
example: '1698472800'
in: query
schema:
type: string
includes:
description: >
Options for enhanced transactions. This query parameter is optional.
Possible additional metadata: `repeating_transactions`, `merchants`,
`classifications`, `geolocations`. The query value is format sensitive.
To retrieve all available enhancements, append:
`?includes=repeating_transactions,merchants,classifications,geolocations`.
The query options may be combined to specific enhancements. For example,
to request Repeating Transactions and Geolocation data, use:
`?includes=repeating_transactions,geolocations`.
- Repeating Transactions: Identifies transactions with predictable
recurrence patterns (e.g., Bill, Income, Subscription).
- Merchants: Enriches 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.
example: repeating_transactions,merchants,classifications,geolocations
in: query
name: includes
required: false
schema:
type: string
schemas:
TransactionsResponseBodyIncludes:
properties:
transactions:
items:
$ref: '#/components/schemas/TransactionIncludesResponse'
type: array
pagination:
$ref: '#/components/schemas/PaginationResponse'
type: object
TransactionIncludesResponse:
allOf:
- $ref: '#/components/schemas/TransactionResponse'
- properties:
classification:
type: object
nullable: true
properties:
parent_class:
example: Deposit
type: string
enum:
- Payroll
- Deposit
- Savings
- Transfer
- Refunds
- Spend
- Investment
- Buy
- Sell
- Income
- Fees
- Expenses
- Corporate Actions
- Other
guid:
example: MNC-3ad50f86-60d0-4545-a1f9-e66c2ac40f69
type: string
geolocation:
nullable: true
type: object
properties:
country:
description: The country name.
example: US
nullable: true
type: string
state:
example: UT
type: string
city:
description: The city name.
example: North Kishaberg
nullable: true
type: string
postal code:
example: '84043'
type: string
merchant:
type: object
nullable: true
properties:
name:
description: The name of the merchant.
example: MX
type: string
guid:
example: MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84
type: string
logo_url:
description: The URL for a 100px X 100px logo for the merchant.
type: string
example: >-
https://content.mx.com/logos/merchants/MCH-0c25f895-393c-42a4-9c18-95a0b26d4d84.png
website_url:
type: string
description: URL to the merchant's website.
example: https://www.example.com
repeating_transaction:
nullable: true
type: object
properties:
repeating_transaction_type:
description: The type of the repeating transaction.
type: string
enum:
- BILL
- SUBSCRIPTION
- INCOME
- UNKNOWN
recurrence_type:
description: The recurrence type of the repeating transaction.
type: string
enum:
- EVERY_OTHER_WEEK
guid:
description: >-
The unique identifier for the repeating transaction. Defined
by MX.
type: string
example: RPT-065b8b1d-826a-45ce-8487-60ca1510e72a
type: object
PaginationResponse:
properties:
current_page:
description: The page delivered by the current response.
example: 1
type: integer
per_page:
description: The number of records delivered with each page.
example: 25
type: integer
total_entries:
description: The total number of records available.
example: 1
type: integer
total_pages:
description: The total number of pages available.
example: 1
type: integer
type: object
TransactionResponse:
properties:
account_guid:
description: The unique identifier for an account. Defined by MX.
example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
nullable: false
type: string
account_id:
description: The unique client-defined identifier for the account.
example: account123
nullable: true
type: string
amount:
description: The monetary amount of the `transaction`.
example: 61.11
nullable: true
type: number
category:
description: The category of the `transaction`.
example: Paycheck
nullable: true
type: string
category_guid:
description: The unique identifier for the category. Defined by MX.
example: CAT-b6d61a19-30a7-e852-2703-bdfb4072289e
nullable: true
type: string
check_number_string:
description: The check number for the `transaction`.
example: null
nullable: true
type: string
created_at:
description: >-
The date and time the transaction was created, represented in ISO
8601 format with a timestamp.
example: '2025-02-13T18:08:00+00:00'
nullable: true
type: string
currency_code:
description: The three-character ISO 4217 currency code, for example, `USD`.
example: USD
nullable: true
type: string
date:
description: >-
The date on which the transaction took place. This is the field used
when searching for transactions by date and is generally the same as
`transacted_at`, but uses `posted_at` as a fallback.
example: '2024-12-20'
nullable: true
type: string
description:
description: A human-readable description of the transaction.
example: MX Technologies Payroll
nullable: true
type: string
extended_transaction_type:
description: The transaction type assigned by the partner.
example: null
nullable: true
type: string
guid:
description: The unique identifier for the transaction. Defined by MX.
example: TRN-429ad9fe-a1d2-4559-8590-885b2603f0e1
nullable: true
type: string
id:
description: The unique partner-defined identifier for the transaction.
example: 1734681600000-178fa8095c154a55b9172f977b4c5f9a-0
nullable: true
type: string
is_bill_pay:
description: Indicates whether the transaction is a bill payment.
example: false
nullable: true
type: boolean
is_direct_deposit:
description: Indicates whether the transaction is a direct deposit.
example: false
nullable: true
type: boolean
is_expense:
description: Indicates whether the transaction is an expense.
example: false
nullable: true
type: boolean
is_fee:
description: Indicates whether the transaction is a fee.
example: false
nullable: true
type: boolean
is_income:
description: Indicates whether the transaction is income.
example: true
nullable: true
type: boolean
is_international:
description: >-
Indicates whether the transaction is international. If the data
provider determines it isn't international then it will be `false`.
It will be `null` if the data provider does not have this
information.
example: false
type: boolean
is_manual:
description: >-
Indicates whether the transaction was manually created or belongs to
a manual account.
example: false
nullable: true
type: boolean
is_overdraft_fee:
description: Indicates whether the transaction is an overdraft fee.
example: false
nullable: true
type: boolean
is_payroll_advance:
description: Indicates whether the transaction is a payroll advance.
example: false
nullable: true
type: boolean
is_recurring:
description: Deprecated. If required, reach out to MX to discuss an alternative.
example: null
nullable: true
type: boolean
is_subscription:
description: Indicates whether the transaction is a subscription payment.
example: false
nullable: true
type: boolean
latitude:
description: >-
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).
example: null
nullable: true
type: number
localized_description:
description: >-
A human-readable description of the transaction, provided in a local
language.
example: This is a localized_description
nullable: true
type: string
localized_memo:
description: >-
Additional descriptive information about the transaction, provided
in a local language.
example: This is a localized_memo
nullable: true
type: string
longitude:
description: >-
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 longitude is 139.691706).
example: null
nullable: true
type: number
member_guid:
description: The unique identifier for the member. Defined by MX.
example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
nullable: true
type: string
member_is_managed_by_user:
description: >-
This indicates whether the member is managed by the user or the MX
partner. Members created with the managed member feature will have
this field set to `false`.
example: true
nullable: true
type: boolean
memo:
description: Additional information about the transaction.
example: Transactions
nullable: true
type: string
merchant_category_code:
description: The ISO 18245 category code for the transaction.
example: null
nullable: true
type: integer
merchant_guid:
description: The unique identifier for the merchant. Defined by MX.
example: MCH-8cc3b01a-1c52-47d4-970d-30f8ee5566f1
nullable: true
type: string
merchant_location_guid:
description: The unique identifier for the merchant location. Defined by MX.
example: null
nullable: true
type: string
metadata:
description: Additional information you stored about the `transaction`.
example: some metadata
nullable: true
type: string
original_description:
description: >-
The original description of the transaction as provided by our data
feed.
example: MX TECHNOLOGIES PAYMENT
nullable: true
type: string
posted_at:
description: The date and time the transaction was posted to the account.
example: '2024-12-20T12:00:00Z'
nullable: true
type: string
status:
description: >
The status of the transaction.
All transaction data on our systems represent what we get through
our data feed which depends 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.
example: POSTED
type: string
nullable: true
enum:
- POSTED
- PENDING
top_level_category:
description: The parent category assigned to this transaction's category.
example: Income
nullable: true
type: string
transacted_at:
description: The date and time the transaction took place.
example: '2024-12-20T12:00:00Z'
nullable: true
type: string
type:
description: The type of transaction.
example: CREDIT
nullable: true
type: string
enum:
- CREDIT
- DEBIT
updated_at:
description: >
The date and time the resource was last updated in ISO 8601 format
with a timestamp.
For categories, this field will always be `null` when `is_default`
is `true`.
example: '2025-02-13T18:09:00+00:00'
nullable: true
type: string
user_guid:
description: The unique identifier for the user. Defined by MX.
example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
nullable: true
type: string
user_id:
description: The unique partner-defined identifier for the user.
example: u-1234
nullable: true
type: string
type: object
securitySchemes:
basicAuth:
scheme: basic
type: http
description: >
The MX Platform API requires basic access authentication using your
`client_id` and `api_key`. These credentials must be Base64 encoded and
included in the Authorization header of each API request to ensure
secure access.
Here's an example using curl to access `v20250224`. Replace
`https://int-api.mx.com/endpoint` with the actual API endpoint you wish
to access and your Base64 encoded `client_id` and `api_key`.
```
curl -L -X POST `https://int-api.mx.com/endpoint' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Accept-Version: v20250224'
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'
```
````