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:
/authorization_code:
post:
description: >-
Clients use this endpoint to request an authorization code according to
the parameters specified in the scope. Clients then pass this code to
processors. Processor access is scoped only to the GUIDs and features
specified in this request. Before requesting an authorization code which
includes a member in the scope, clients must have verified that member.
operationId: requestAuthorizationCode
parameters:
- $ref: '#/components/parameters/acceptVersion'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationCodeRequestBody'
description: The scope for the authorization code.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationCodeResponseBody'
description: OK
summary: Request an authorization code
tags:
- processor token
/ach_returns/{ach_return_guid}:
get:
description: |
Use this endpoint to get an ACH return by its `guid` or `id`.
operationId: readACHRetrun
parameters:
- $ref: '#/components/parameters/achReturnGuid'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ACHReturnResponseBody'
description: OK
summary: Read ACH Return
tags:
- ach return
/ach_returns:
get:
description: |
Use this endpoint to get all ACH returns.
operationId: listACHRetruns
parameters:
- $ref: '#/components/parameters/institutionGuid'
- $ref: '#/components/parameters/returnedAt'
- $ref: '#/components/parameters/resolvedStatusAt'
- $ref: '#/components/parameters/returnCode'
- $ref: '#/components/parameters/returnStatus'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPage'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ACHReturnsResponseBody'
description: OK
summary: List ACH Returns
tags:
- ach return
post:
description: |
Use this endpoint to create an ACH return in our system.
operationId: createACHReturn
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ACHReturnCreateRequestBody'
description: ACH return object to be created.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ACHReturnResponseBody'
description: OK
summary: Create ACH Return
tags:
- ach return
/categories/default:
get:
description: >-
Use this endpoint to retrieve a list of all the default categories and
subcategories offered within the MX Platform API. In other words, each
item in the returned list will have its `is_default` field set to
`true`. There are currently 119 default categories and subcategories.
Both the _list default categories_ and _list default categories by user_
endpoints return the same results. The different routes are provided for
convenience.
operationId: listDefaultCategories
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPage'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CategoriesResponseBody'
description: OK
summary: List default categories
tags:
- categories
/categories/{category_guid}:
get:
description: Use this endpoint to read the attributes of a default category.
operationId: readDefaultCategory
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/categoryGuid'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryResponseBody'
description: OK
summary: Read a default category
tags:
- categories
/institutions:
get:
description: >-
Lists financial institutions available through the MX platform. This
endpoint has been updated in `v20250224` to enhance search and filtering
capabilities based on the products supported by each institution.
operationId: listInstitutions
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/institutionName'
- $ref: '#/components/parameters/isoCountryCode'
- $ref: '#/components/parameters/includeBlockedInstitutions'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPageMax1000'
- $ref: '#/components/parameters/supportedProducts'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InstitutionsResponseBody'
description: OK
summary: List institutions
tags:
- institutions
/institutions/favorites:
get:
description: >-
This endpoint returns a paginated list containing institutions that have
been set as favorites, sorted by popularity. Please contact MX to set a
list of favorites.
operationId: listFavoriteInstitutions
parameters:
- $ref: '#/components/parameters/isoCountryCode'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPageMax1000'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InstitutionsResponseBody'
description: OK
summary: List favorite institutions
tags:
- institutions
/institutions/{institution_code}:
get:
description: >-
This endpoint returns information about the institution specified by
`institution_code`. The `v20250224` update enhances the granularity of
the information provided about the services and products supported by
the institution.
operationId: readInstitution
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/institutionCode'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InstitutionResponseBody'
description: OK
summary: Read institution
tags:
- institutions
/institutions/{institution_identifier}/credentials:
get:
description: >
Use this endpoint to see which credentials will be needed to create a
member for a specific institution.
Passing an invalid `institution_identifier` returns a `404`.
operationId: listInstitutionCredentials
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/institutionIdentifier'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPageMax1000'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialsResponseBody'
description: OK
summary: List institution credentials
tags:
- institutions
/managed_institutions:
get:
description: >
This endpoint returns a list of institutions which can be used to create
partner-managed members.
<Warning>
This endpoint has been deprecated. For more information, reference the
[Migration guide](/api-reference/platform-api/overview/migration)
</Warning>
operationId: listManagedInstitutions
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPageMax1000'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InstitutionsResponseBody'
description: OK
summary: List managed institutions
tags:
- managed data [deprecated]
deprecated: true
/merchant_locations/{merchant_location_guid}:
get:
description: >-
This endpoint returns the specified `merchant_location` resource. The
`merchant_location_guid` can be found on `transaction` objects.
operationId: readMerchantLocation
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/merchantLocationGuid'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantLocationResponseBody'
description: OK
summary: Read merchant location
tags:
- merchants
/merchants:
get:
description: >-
This endpoint returns a paginated list of all the merchants in the MX
system.
operationId: listMerchants
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/merchantName'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPageMax1000'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantsResponseBody'
description: OK
summary: List merchants
tags:
- merchants
/merchants/{merchant_guid}:
get:
description: >-
Returns information about a particular merchant, such as a logo, name,
and website.
operationId: readMerchant
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/merchantGuid'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantResponseBody'
description: OK
summary: Read merchant
tags:
- merchants
/transactions/enhance:
post:
description: >-
Use this endpoint to categorize, cleanse, and classify transactions.
These transactions are not persisted or stored on the MX platform. <br
/><br />For more information on returned data, please see the [Enhanced
Transactions fields
guide](/api-reference/platform-api/reference/transactions-overview#enhanced-transactions).
operationId: enhanceTransactions
parameters:
- $ref: '#/components/parameters/acceptVersion'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnhanceTransactionsRequestBody'
description: Transaction object to be enhanced
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EnhanceTransactionsResponseBody'
description: OK
summary: Enhance transactions
tags:
- transactions
/users:
get:
description: >-
Use this endpoint to list every user you've created in the MX Platform
API.
operationId: listUsers
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPageMax1000'
- $ref: '#/components/parameters/userId'
- $ref: '#/components/parameters/userEmail'
- $ref: '#/components/parameters/userIsDisabled'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponseBody'
description: OK
summary: List users
tags:
- users
post:
description: >-
Use this endpoint to create a new user. The API will respond with the
newly-created user object if successful, containing a `guid` that you'll
set as the `user_guid` in other requests when required. Disabling a user
means that accounts and transactions associated with it will not be
updated in the background by MX. It will also restrict access to that
user’s data until they are no longer disabled.
operationId: createUser
parameters:
- $ref: '#/components/parameters/acceptVersion'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreateRequestBody'
description: >-
User object to be created. (None of these parameters are required, but
the user object cannot be empty)
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponseBody'
description: OK
summary: Create user
tags:
- users
/users/{user_identifier}:
delete:
description: >
Use this endpoint to delete the specified `user`. The response will have
a status of `204 No Content` without an object.
<Warning>
Deleting a user is permanent. Deleted users can never be restored. For
more info, see [Deleting
Objects](/api-reference/platform-api/overview/deleting-objects).
</Warning>
operationId: deleteUser
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/acceptHeader'
- $ref: '#/components/parameters/userIdentifier'
responses:
'204':
description: No Content
summary: Delete user
tags:
- users
get:
description: Use this endpoint to read the attributes of a specific user.
operationId: readUser
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/userIdentifier'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponseBody'
description: OK
summary: Read user
tags:
- users
put:
description: Use this endpoint to update the attributes of the specified user.
operationId: updateUser
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/userIdentifier'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpdateRequestBody'
description: >-
User object to be updated (None of these parameters are required, but
the user object cannot be empty.)
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponseBody'
description: OK
summary: Update user
tags:
- users
/users/{user_identifier}/accounts:
get:
description: >
This endpoint returns a list of all the accounts associated with the
specified `user`.
<Warning>
This request will not return the full account number. It may return the
last four digits of the account number if that information has been
provided during aggregation. If you need the full account number, please
refer to [List account numbers by
member](/api-reference/platform-api/reference/list-account-numbers-by-member/)
or [List account numbers by
account](/api-reference/platform-api/reference/list-account-numbers-by-account/).
</Warning>
operationId: listUserAccounts
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/acceptHeader'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/memberIsManagedByUser'
- $ref: '#/components/parameters/accountIsManual'
- $ref: '#/components/parameters/recordsPerPageMax1000'
- $ref: '#/components/parameters/userIdentifier'
- $ref: '#/components/parameters/useCase'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountsResponseBody'
description: OK
summary: List accounts
tags:
- accounts
post:
description: >
This endpoint can only be used to create manual accounts. Creating a
manual account will automatically create it under the Manual Institution
member. Since a manual account has no credentials tied to the member,
the account will never aggregate or include data from a data feed.
<Warning>
You must use the user `guid` when setting `user_identifier` in the path.
</Warning>
operationId: createManualAccount
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/userIdentifier'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreateRequestBody'
description: Manual account object to be created.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountResponseBody'
description: OK
summary: Create manual account
tags:
- accounts
/users/{user_guid}/accounts/{account_guid}:
get:
description: This endpoint returns the specified `account` resource.
operationId: readAccount
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/accountGuid'
- $ref: '#/components/parameters/userGuid'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountResponseBody'
description: OK
summary: Read account
tags:
- accounts
delete:
description: >-
This endpoint deletes accounts that were manually created. The API will
respond with an empty object and a status of `204 No Content`.
operationId: deleteManualAccount
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/accountGuid'
- $ref: '#/components/parameters/acceptHeader'
- $ref: '#/components/parameters/userGuid'
responses:
'204':
description: No content.
summary: Delete manual account
tags:
- accounts
/users/{user_identifier}/accounts/{account_identifier}/account_numbers:
get:
description: >-
This endpoint returns a list of account numbers associated with the
specified `account`.
operationId: listAccountNumbersByAccount
parameters:
- $ref: '#/components/parameters/acceptVersion'
- $ref: '#/components/parameters/accountIdentifier'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/recordsPerPageMax1000'
- $ref: '#/components/parameters/userIdentifier'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountNumbersResponseBody'
description: OK
summary: List account numbers by account
# --- truncated at 32 KB (430 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mx/refs/heads/main/openapi/mx-platform-api-openapi.yml