Skip to main content

API Versioning

Dated versions of our APIs are released when we introduce backwards-incompatible changes to a generally available product or feature. Changes may be limited to a single endpoint or multiple endpoints. The specific changes are listed in the Versions section, including how to pass version information.

Version support​

On release, versions will have at least 18 months of support. After a new version is announced, a deprecation date will be set. After a year-long deprecation period, versions will sunset.

  • Supported version: Release is actively supported and available on the documentation site for at least 18 months from launch of version or announced deprecation date.
  • Deprecated: Version is still available to use for 12 months after deprecation date. Documentation for deprecated versions will not be updated.
  • Sunset: Twelve months after deprecation date, the version will sunset. Access to the version is removed, attempts to reach the version will return an error.

Breaking changes​

The following are not backwards compatible and will require a new version.

  • Adding a new required request parameter, or converting a previously optional request parameter parameter into a required one
  • Removing a request parameter from the url or body of request (optional or required)
  • Changing the semantic meaning of a parameter
  • Changing the type of parameter
  • Adding a new validation rule to an existing parameter
  • Removing a response field
  • Renaming a response field
  • Removing enum values
  • Altering the existing data structure of a response body to make it non-backwards compatible
  • Altering the kind of data a response field returns (e.g. converting an integer to a string)
  • Removing, moving, or changing endpoint paths

Non-breaking changes​

The following are considered backwards compatible and will not require a new version:

  • Adding new API endpoints
  • Adding an optional request header
  • Adding new optional parameters to existing endpoints
  • Adding new data elements to existing response schemas
  • Adding a new response header
  • Changing the order of properties in existing API responses
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings
  • Converting a previously required request parameter into an optional parameter
  • Sunsetting an existing, deprecated version

Versions​

An overview of breaking changes for each version is listed below. For more information on backwards-compatible (non-breaking) changes review our Changelog.

v20250224​

info

If your implementation uses a previous version, please reference the Migration guide.

Set this version in the Accept-Version header of API requests.

Example


_10
-H 'Accept: application/json'
_10
-H 'Accept-Version: v20250224'

Supported products​

v20250224 enhances search and filtering capabilities based on products supported by each institution. This update includes breaking changes to several endpoints with changes to some parameters and deprecated response data fields.

Impacted endpoints

QueriesReponsesDeprecated fields
GET /institutionsGET /institutions
GET /institutions/{institution_code}		supports_account_verification
supports_account_identification
supports_transaction_history
supports_account_statement

A new supported_products array replaces these data fields and contains values such as: account_verification, identity_verification, transactions, and transaction_history.

Data Request​

A new field, data_request is now required in the request body of updated endpoints and contains a products array of values such as: account_verification, identity_verification, transactions, and history.

Queries & ReponsesRequired fields
POST /users/{user_guid}/members
POST /users/{user_guid}/widget_urls		data_request

Deprecated fields​

The skip_aggregation field is now deprecated. Aggregation is assumed to be required unless specified otherwise in the data_request.products configuration.

Deprecated endpoints​

  • /managed_institutions
  • /users/{user_guid}/managed_members
  • /users/{user_guid}/managed_members/{member_guid}
  • /users/{user_guid}/managed_members/{member_guid}/accounts
  • /users/{user_guid}/managed_members/{member_guid}/accounts/{account_guid}
  • /users/{user_guid}/managed_members/{member_guid}/accounts/{account_guid}/transactions
  • /users/{user_guid}/managed_members/{member_guid}/accounts/{account_guid}/transactions/{transaction_guid}

Sunset endpoints​

Previously deprecrated endpoints are no longer documented with v20250224:

  • /payment_processor_authorization_code
  • /users/{user_guid}/connect_widget_url

v20111101 (v1)​

If you are new to MX, this version is not recommended. If you are a current user of this version, use the recommended header:

-H 'Accept-Version: v20111101'

On this page