Introduction

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.

The MX API is built around a standard REST architecture, uses predictable, resource-oriented URLs, and returns all data in JSON format. Requests are made with HTTP methods and HTTP response codes indicate the success or failure of those requests.

API architecture and resource structure

The MX Platform API has many different resources and features, but once you break it down, it is centered around five major resource types. Virtually all the others are connected in one way or another with the resources described here.

Resource Description
institution An institution represents a financial institution (FI) like Chase or Wells Fargo. It’s important to point out that many real-world FI will actually have several different institution objects within the MX Platform API. This is because, for example, the mortgage division of Wells Fargo might use a separate system than its everyday banking division, which is different from its credit card division, etc.
user A user represents an end-user accessing the MX Platform API via your application, be it a mobile app, web app, desktop app, etc.
member A member represents the relationship between a user and an institution. A user may have multiple members, one each for their bank, their mortgage broker, their credit card provider, etc. Aggregation, verification, and many other processes are centered around a member, meaning this is probably the most important type of object you’ll be working with.
account An account represents a financial account held by an FI, e.g., a user’s checking or savings account. A member may have more than one account associated with it. For instance, a user may have both a checking and savings account associated with one Chase login and would therefore have two accounts associated with that member.
transaction A transaction represents any instance in which money moves into or out of an account, such as a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, etc. Each transaction belongs to only one account.

Authentication and security

MX Platform API requests must use HTTPS with TLSv1.2 encryption or higher or else they will fail.

Requests also require basic access authentication where your client_id is the username and your api_key is the password. These values are available on the client dashboard.

Technically, basic access authorization requires the Base64 encoding of these values separated by a colon, but many HTTP clients will handle the encoding for you. For instance, all cURL example requests in this documentation use the -u option, e.g., -u 'client_id:api_key'. Nevertheless, there is an example of Base64 encoding to the right.

Because the values described above may grant access to some or all of your data, you must keep them secret and keep them safe. Do not share them in public areas, use them in client-side code, or otherwise use them in a way that may compromise their security.

All requests must come from a whitelisted IP address, which is configured via the client dashboard. Any request from a non-whitelisted IP address will return a 403 Forbidden error. IP addresses outside of the United States are normally not permissible, so any requests for non-US IPs will require additional scrutiny and will be manually investigated and approved. Should we have any questions or need further details, MX will contact you via email.

In some instances, requests that require authentication will return 404 Not Found, instead of 401 Unauthorized. This is to prevent leaking private information.

Basic authorization value

Base64 encoding of:
client_id:api_key

Example

CLIENT-1234:API-KEY-4567 -> Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3

Base URL

MX uses separate base URLs for its development and production environments. All examples given in this reference use the development base URL.

Development URL

https://int-api.mx.com

Production URL

https://api.mx.com

Caching

Certain API resources are subject to change at any time; for instance, institutions. For this reason, we discourage you from caching lists of resources. If caching is necessary, we recommend refreshing a cached list at least daily.

Character encoding

Requests to the API must use characters encoded with the UTF-8 standard.

Data format

JSON structured data is expected in all requests and returned in all responses, including some errors.

Dates and times

Dates and times are always given in ISO 8601 format.

Fields which end in _on are given without a timestamp: 2018-07-18

Fields which end in _at are given with a timestamp: 2015-04-13T12:01:23Z.

Deleting objects

When deleting an object on the MX platform, all objects belonging to that object are also deleted in a cascading fashion. For example, deleting a member deletes not just the member, but all associated accounts, transactions, holdings, etc. Deleting a user also deletes all members associated with it, and so on.

Objects are “soft-deleted” first, meaning they are inaccessible for two weeks, but remain on the MX platform. This helps us accommodate end users who delete and then re-create a member with identical credentials, as well as facilitate support requests and possible fraud investigations. Soft-deleted objects are permanently deleted after this this period.

Errors

The MX Platform API uses conventional HTTP response codes to indicate the success or failure of a request, with supplementary error messaging as needed within response bodies.

Status codes

Status Explanation
2xx Success
200 OK Everything worked as expected with content returned.
202 Accepted
  1. Everything worked and MX’s system is processing the request.
  2. When attempting a job on a member, a job of the same type is already running; e.g., calling aggregate member while a standard agg is still running, or calling verify member while a previous verification is still running.
  3. A standard aggregation has been attempted within the default minimum time between standard aggs.
204 No Content Everything worked as expected without content returned.
4xx Requester error
400 Bad Request Often, this means a required parameter was missing.
401 Unauthorized Invalid MX-API-Key or MX-Client-ID provided.
403 Forbidden The request was made from a non-whitelisted address or the feature is not available to the client.
404 Not Found Invalid item/id/URL requested.
405 Method Not Allowed A constraint on the requested endpoint wasn’t met.
406 Not Acceptable The request didn’t specify a valid API version.
409 Conflict 1. An object with the given attributes already exists.

2. When attempting an aggregation on a member, the member already has an an aggregation of a different type running; e.g., calling the verify endpoint while a standard aggregation is already running, or calling fetch statements while an identification aggregation is already running.
422 Unprocessable Entity The data provided cannot be processed.
5xx Responder error — which are rare
500, 502, 504 Server errors Something went wrong with MX’s servers.
503 Service Unavailable The MX Platform is being updated.

Example error message

1
2
3
4
5

{
  "error": {
    "message": "Unrecognized institution.",
  }
}

Headers

In addition to the required Authorization header, each request also requires an Accept header. POST and PUT requests also require a Content-Type header.

'Content-Type: application/json'

'Accept: application/vnd.mx.api.v1+json'

Identifiers and metadata

All updateable resources created with the API support an optional metadata field. You can use the metadata field to store structured (key-value) data about a resource. For example, you could store a user’s username for your system, their sign-up date, the date and time of their last logon in your system, or all of these. Metadata is not used by MX.

Do not store sensitive information as metadata.

Updateable resources also contain an id field. For instance, you may need to make certain that some resources are created only once or may need to sync data on the MX platform with data on your own platform. In these situations, you can give a unique id to resources created with the MX Platform API. The API will return a 409 Conflict error if a resource is created with an id that already exists.

Limits on the API

Aggregation throttling

Standard aggregations are throttled after any type of job is attempted for a specific member (including verification, balance, history, identity, statements, and standard agg). The default throttle period is three hours (10,800 seconds), though this limit can vary from one institution to another. In other words, you generally cannot re-aggregate a member within three hours of any kind of job on a member. Members that have experienced credential-related errors won’t be throttled (connection_status: REJECTED, PREVENTED, UPDATED).

Throttled aggregations will not return an error; the response will have a status of 202 Accepted and contain the current state of the member, including the latest connection_status.

Premium jobs are never throttled. That is, you can run an account verification right after another verification has finished (or balance request, or agg, etc.). However, because standard aggs are throttled after premium jobs, you should generally use the include_transactions parameter to prevent any delays if standard data is needed at the same time as premium data.

There is no throttling of any kind when using the MX Bank test institution.

Data availability

Be aware that aggregation is not guaranteed to return all relevant information or even every data point on a given resource. For instance, aggregation may return the balance of an account, but return a null value for the apr and apy fields. This is to be expected in all resources and all aggregations.

Request rate limits

For startup partners, requests to the API are limited to 100 per minute in total, with a total of 100 records allowed per request. Startup partners are granted an additional one request per minute for every 100 users on the MX platform.

However, partners can also be allotted far larger rates. If you require a larger volume, reach out to your MX client strategy consultant.

Given these limitations, partners should not perform load testing on the API.

User and member limits

The development environment limits developers to 100 users and access to only some of the top financial institutions.

No user may have more than 25 members in either the development or production environments.

Pagination

All endpoints which return lists are paginated. These endpoints also support two query parameters which specify the number of records per page and the page to be returned.

Each response will include a pagination object specifying information on the total number of entries and the current page.

Query parameters

Parameter Definition
page This specifies the page to be returned. Defaults to 1.
records_per_page This specifies the number of records to be returned on each page. Defaults to 25. The valid range is from 10 to 100.

Pagination fields

Field Definition
current_page The page delivered by the current response.
per_page The number of records delivered with each page.
total_entries The total number of records available.
total_pages The total number of pages available.

Example pagination object

1
2
3
4
5
6

"pagination": {
  "current_page": 1,
  "per_page": 25,
  "total_entries": 2,
  "total_pages": 1
}

Versioning

We always try to make API changes backwards-compatible. However, when we make breaking changes to the MX Platform API, we’ll increment the version number. The current version is v1. Versions are specified in a request’s Accept header. All requests will access the current version unless a different version is specified with the request, so it’s best to always specify the API version. The current Accept header is application/vnd.mx.api.v1+json.

The Connect widget

Connect is a ready-made and embeddable application that allows you to quickly add members to the MX platform and navigate the complex aggregation process. It searches for institutions, creates new members, gathers credentials, prompts for MF, resolves errors, and can start verification and aggregation jobs.

You can use Connect by embedding it in a website with an iframe or a mobile application with a WebView. Both iframe and WebView implementations require their own specific configurations and handling of message events.

Request a Connect URL

This endpoint allows partners to get a URL by passing the widget_type in the request body, as well as configuring it in several different ways. In the case of Connect, that means setting the widget_type to connect_widget.

Partners may also pass an optional Accept-Language header as well as a number of configuration options.

Note that this is a POST request.

Configuration options

Configuration option Description Type Widget
color_scheme Load the Connect widget in the specified color_scheme; options are light and dark. Defaults to light. String Connect
current_institution_code Load the widget into the credential view for the specified institution. String Connect
current_institution_guid Load the widget into the credential view for the specified institution. String Connect
current_member_guid Load to a specific member that contains an error or requires MFA from the most recent job. current_member_guid takes precedence over current_institution_code. String Connect
disable_institution_search When set to true, the institution search feature will be disabled and end users will not be able to navigate to it. Must be used with current_institution_code, current_instituion_guid, or current_member_guid. Boolean Connect
include_transactions When set to false while creating or updating a member, transaction data will not be automatically aggregated. Future manual or background aggregations will not be affected. Defaults to true. Boolean Connect
is_mobile_webview Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages. Boolean All
mode Loads the Connect widget into a specified mode; options are verification and aggregation. Defaults to aggregation. String Connect
oauth_referral_source This determines how MX will respond to the result of an OAuth flow.

When set to APP, MX will redirect to the URI specified in the ui_message_webview_url_scheme.

When set to BROWSER, MX will send a postMessage but not redirect.

If is_mobile_webview is true, this defaults to APP. If false, it defaults to BROWSER. See this guide for more details.		 String Connect
ui_message_version Use this to specify which version of postMessage events are triggered. All new implementations must use version 4. Prior versions are deprecated. Integer Connect
ui_message_webview_url_scheme Used in postMessages and OAuth redirects in WebViews. Defaults to mx. String Connect
update_credentials Loads widget to the update credential view of a current member. Optionally used with current_member_guid. This option should be used sparingly. The best practice is to use current_member_guid and let the widget resolve the issue. Boolean Connect
wait_for_full_aggregation Loads Connect, but forces the widget to wait until any aggregation-type process is complete in order to fire a member connected postMessage. This allows clients to have transactional data by the time the widget is closed. Boolean Connect
widget_type Use this to specify which widget you would like to load. String Connect

Endpoint:

POST /users/{user_guid}/widget_urls

1
2
3
4
5
6
7
8
9
10

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "color_scheme": "dark"
      }
    }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Example request with language header

1
2
3
4
5
6
7
8
9
10
11

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-H 'Accept-Language: en-CA' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key' \
-H 'Content-Type: application/json'
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "color_scheme": "dark"
      }
    }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Request a Connect URL (deprecated)

This legacy endpoint allows partners to request a URL specifically for the Connect widget. While we continue to support this endpoint for existing partners, it should not be used in new integrations. Instead, use the request widget URL endpoint documented both above and under the heading on widgets below.

This endpoint accepts any configuration option relevant to the Connect widget.

Endpoint:

POST /users/{user_guid}/connect_widget_url

1
2
3
4
5
6
7
8
9

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/connect_widget_url \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "config": {
          "color_scheme": "dark"
        }
      }'

1
2
3
4
5
6

{
  "user": {
    "connect_widget_url": "https://int-widgets.moneydesktop.com/md/connect/52bxfvvvm0p1qyb9As6737366AZyw3x3c07gzflsqbjwA5gA0snwnAb2Ams468zz6gg0wA3yvfbsx2c9m6cfljf0zgznnlAmhy3tczmr987bxqbxd2785jfbs48k003v28mxt0xh16vAxjk6rv9h2rwxgbzwdyd9xsvlk82dl01yw3sp1wn68wb5gbn9v6kdy1wtgwl92sppxrzyp0rjvsgqclsyjwhbAgr5mqsAlw730hz3w9rl7vlp2pspAhn5gx1xxdbsz6lkmwlcA6tdfqzgpk6nh126kA89zqm7tk0qg3zd2nA7dgnkg14nw5bgyczb80Ad0sxrm6msvb2kw1c80dxc984f8p7bzb5y/eyJ1aV9tZXNzYWdlX3ZlcnNpb24iOjEsInVpX21lc3NhZ2Vfd2Vidmlld191cmxfc2NoZW1lIjoiYXRyaXVtIn0%3D",
    "guid": "USR-29eab3cf-6a87-fe97-6279-563b63e75a53"
  }
}

Minimum dimensions and breakpoints

Connect uses a responsive design. Page styles and layout are subject to change, and elements may become hidden or visible at different widths.

The following are the minimum dimensions supported for mobile and desktop platforms.

  • Minimum height: 550px
  • Minimum width: 320px

Below are the width breakpoints at which the design may change. These are based on typical industry device resolutions. These are subject to change in the future.

  • Small: 320px to 767px
  • Medium: 768px to 1199px
  • Large: 1200px or greater

Configuring Connect

Configuring the MX Connect widget really unlocks the potential and power of the widget. Configuration will help you with tasks like loading the widget for a specific institution, answering MFA, fixing a member in bad state, and more. You’ll find a list of configuration scenarios and example requests below.

Configuration scenarios

Scenario Settings
Answer MFA for a specific member Set the current_member_guid to a member whose connection_status is CHALLENGED. Connect will load the MFA view so the end user can respond to the MFA challenge.
Resolve a member’s error(s) Set the current_member_guid option to a member in an error state. Connect will load in the error view so the end user can resolve the error.
Run verification with a specific institution Set the current_institution_code option to the desired institution’s code, and set the mode option to verification. Connect will load the login view for that institution.
Run aggregation with a specific institution Set the current_institution_code option to the desired institution’s code, but do not set the mode option. Connect will load the login view for that institution.
Run aggregation but exclude transactions Set the include_transactions option to false when creating or updating a member. Connect will not automatically aggregate transaction data. Future manual or background aggregations will not be affected.
Disable search when loading a specific institution Set disable_institution_search option to true and set the current_institution_code or current_member_guid option. Connect will load the login view for the specified institution, but will not allow the end user to navigate to the search view.
Update a member’s credentials Set the current_member_guid to the desired member’s GUID, and set the update_credentials option to true. Connect will load the update credentials view for the member. This option should be used sparingly. It is best practice to only use current_member_guid and let the widget take care of things.
Get the member connected postMessage after aggregation is complete Set wait_for_full_aggregation option to true and load Connect normally. Connect will wait for the aggregation job to complete before sending the member connected postMessage. This ensures that transaction data is available before moving on.

Excluding transaction data

Sometimes you don’t need transaction data right away, or you may be concerned that gathering transaction data may take some time and delay your preferred flow. For those who don’t need the transaction data up front, you can use set the include_transactions option to false to potentially speed up a first-time aggregation.

1
2
3
4
5
6
7
8
9
10

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "include_transactions": false
        }
      }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Loading a specific institution

MX Connect can be loaded directly into a specific institution for gathering credentials.

You should consider using this configuration with the disable_institution_search option to prevent the end user from going back to the search and loading a separate institution manually.

1
2
3
4
5
6
7
8
9
10

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "current_institution_code": {bank code}
        }
      }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Loading a specific member

MX Connect can prompt for MFA, updating old credentials, or “repair” members that are in a bad state. This is done by loading Connect directly into a specific member.

Rather than trying to figure out what do with with each and every connection_status, it is often best to simply load Connect with the member_guid in question and allow it to automatically determine the best course of action for the end user.

You should consider using this configuration with the disable_institution_search option to prevent the end user from going back to the search to create a new member.

MX does not recommend using this configuration with the update_credentials option.

1
2
3
4
5
6
7
8
9
10

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "current_member_guid": {member_guid}
        }
      }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Mobile webviews

It is imperative that you correctly configure Connect when embedding in a WebView. See the WebView section for more information.

Verification mode

Setting the mode to verification will change several behaviors in Connect:

  1. The end user will be prompted to verify an existing connection (if they have one) before going to search.
  2. Connect will only search for and display institutions that support verification.
  3. After gathering credentials, Connect will start a verification job rather than an aggregation job.
1
2
3
4
5
6
7
8
9
10

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "mode": "verification"
        }
      }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Waiting for a full aggregation

By default, Connect will complete its flow once the member has a connection_status of CONNECTED. At this point, the member is connected to the financial institution, but account and transaction data may not be gathered yet.

If you would like Connect to wait for account, transaction, or verification data before finishing its flow, use the wait_for_full_aggregation option.

1
2
3
4
5
6
7
8
9
10

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "wait_for_full_aggregation": true
        }
      }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Connect Javascript Loader

Once you’ve generated a URL, you can pass that information on to a JavaScript loader provided by MX. This loader allows you to further configure your Connect widget, including the size as well as all the supported configuration options, inside the config object.

It also allows you to listen for event messages that indicate loading or a successful member creation.

Parameters available for the JavaScript loader

Parameter Data Type Description Required?
config Object This object allows you to set additional parameters to load the MX Connect widget in a specific state. No
height String Desired height of the iframe. Defaults to 600 pixels. No
id String The id of the DOM element you’ll load the widget into. Yes
onEvent Function A general event handler. Only available with ui_message_version: 4 or higher, which is the required version for the MX Platform API. No
width String Desired width of the iframe. Defaults to 100% of the parent. No
url String A URL for the widget provided as a response to the POST request above. Yes
Example usage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<script src="https://atrium.mx.com/connect.js"></script>
/**
 * The reference to "atrium" is a holdover from a legacy API.
 * Nevertheless, this is still the correct source for the widget loader
 * even in the context of the Platform API.
 */

<script>
var mxConnect = new window.MXConnect({
  id: "connect-widget",
  iframeTitle: "Connect",
  /**
   * Callback that for handling all events within Connect.
   * Only called in  ui_message_version 4 or higher.
   *
   * The events called here are the same events that come through post
   * messages.
   */
  onEvent: function (type, payload) {
    console.log("onEvent", type, payload);
  },
  config: {
    ui_message_version: 4
  },
  targetOrigin: "*",
})
</script>

Embedding in WebViews

Because of the technical limitations of WebView-based implementations, an alternative to standard postMessages is required. If Connect is configured with is_mobile_webview set to true, we will use navigation events with window.location = url instead of window.postMessage(message)

ui_message_webview_url_scheme will be mx:// by default.

Example navigation event schema

{ui_message_webview_url_scheme}://{some/path}?metadata={jsonString}

Suggested base configuration for WebViews

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "is_mobile_webview": true,
          "ui_message_version": 4,
          "ui_message_webview_url_scheme": "{app_scheme}"
        }
      }'

# Possible navigation events based on the config above:
# `mx://load`
# `yourAppScheme://connect/institutionSearch?metadata={...json...}

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}
Code Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

public class MainActivity extends AppCompatActivity {
    private WebView webView = null;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      webView = (WebView) findViewById(R.id.webview);
      webView.setWebViewClient(new ConnectWebviewClient());
      webView.getSettings().setDomStorageEnabled(true);
      webView.getSettings().setJavaScriptEnabled(true);
    }
    private class ConnectWebviewClient extends WebViewClient {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
            if (url.startsWith("mx://")) {
                return true;
            }
            return false;
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

class ViewController: UIViewController, WKUIDelegate {
  override func viewDidLoad() {
      super.viewDidLoad()
      webView.delegate = self
      ...
  }

  func webView(_ webView: WKWebView, decidePolicyFor
    navigationAction: WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {

    // Intercept custom URI
    let surl = navigationAction.url?.absoluteString
    if (surl?.hasPrefix("mx://"))! {
      // Take action here

      // Cancel request
      decisionHandler(.cancel)
      return
    }

    // Allow request
    decisionHandler(.allow)
  }
}

Dealing with OAuth in WebViews

There are three configuration options WebViews will need in order to have the optimal OAuth flow:

  • is_mobile_webview: true: Allows the widget to know if it is in a WebView context.
  • ui_message_version: 4: Allows the widget to send new postMessage events.
  • ui_message_webview_url_scheme: <your app>: Determines message scheme; this is is used by MX to redirect the user back to the client app in mobile contexts.

In-depth configuration documentation can be found here.

In-depth documentation on postMessages can be found here.

1
2
3
4
5
6
7
8
9
10
11
12

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "is_mobile_webview": true,
          "ui_message_version": 4,
          "ui_message_webview_url_scheme": "{app_scheme}"
        }
      }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Redirecting the user

Since the MX WebView can’t reliably send the user from the app to the OAuth provider’s site in a native browser, the containing iOS or Android app will need to. To facilitate this, your app will need to react to the connect/oauthRequested postMessage request:

<ui_message_webview_url_scheme>://connect/oauthRequested?metadata=...

The OAuth URL is inside of the metadata query parameter under the url key.

Redirecting the user

Example redirect with Java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

/**
 * This Client will capture urls from MX and cancel them. It will specifically
 * handle the oauthRequested URL. You will want to set this client as your
 * WebView's client or add this functionality to your own.
 */
public class MXWebViewClient extends WebViewClient {
    private Activity activity;

    public MXWebViewClient(Activity mainActivity) {
        activity = mainActivity;
    }

    @Override
    public boolean shouldOverrideUrlLoading(WebView view, String url) {
        // Ensure you are looking for schemes from 'mx' and whatever you configured
        // ui_message_webview_url_scheme to be. In this example, it was 'appscheme'.
        boolean isFromMX = url.startsWith("mx://")  || url.startsWith("appscheme://");

        if (isFromMX) {
            try {
                Uri mxURI = Uri.parse(url);

                // Handle the oauth url redirect. Send the user to the URL given.
                if (mxURI.getPath().equals("/oauthRequested")) {
                    JSONObject mxMetaData = new JSONObject(mxURI.getQueryParameter("metadata"));
                    String oauthURL = mxMetaData.getString("url");
                    Uri oauthPage = Uri.parse(oauthURL);
                    Intent intent = new Intent(Intent.ACTION_VIEW, oauthPage);
                    activity.startActivity(intent);
                }
            } catch (Exception err) {
                Log.e("sb: Error creating URI", err.getMessage());
            }
            return true;
        }

        return false;
    }
}

Example redirect with Swift

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

/**
 * Set up the WebView to capture URLs. You will want to cancel all urls from MX.
 */
class ViewController: UIViewController, WKNavigationDelegate {

    var webView: WKWebView!
    let appScheme = "appscheme://"
    let mxScheme = "mx://"

    func webView(_ webView: WKWebView,
                 decidePolicyFor navigationAction: WKNavigationAction,
                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {

        // Ensure you are looking for schemes from both 'mx' and whatever you configured
        // ui_message_webview_url_scheme to be. In this example, it was 'appscheme'.
        let url = navigationAction.request.url?.absoluteString
        let isFromMX = url?.hasPrefix(appScheme) == true || url?.hasPrefix(mxScheme) == true

        if isFromMX {
            let urlc = URLComponents(string: surl ?? "")
            let path = urlc?.path ?? ""
            // there is only one query parameter ("metadata")
            // so just grab the first one
            let metaDataQueryItem = urlc?.queryItems?.first

            if path == "/oauthRequested" {
                handleOauthRedirect(payload: metaDataQueryItem)
            }

            // Cancel request
            decisionHandler(.cancel)
            return
        }

        // Allow request
        decisionHandler(.allow)
    }

    /*
     * Handle the oauthRequested event. Parse out the OAuth URL from the event
     * and open Safari to that URL
     * NOTE: This code is somewhat optimistic, you'll want to add error handling
     * that makes sense for your app.
     */
    func handleOauthRedirect(payload: URLQueryItem?) {
        let metadataString = payload?.value ?? ""

        do {
            if let json = try JSONSerialization.jsonObject(with: Data(metadataString.utf8), options: []) as? [String: Any] {
                if let url = json["url"] as? String {
                    // open safari with the url from the json payload
                    UIApplication.shared.open(URL(string: url)!)
                }
            }
        } catch let error as NSError {
            print("Failed to parse payload: \(error.localizedDescription)")
        }
    }
}

Getting back to your app

Once the user completes the OAuth process, MX will send the user back to the client app via a URL scheme like so:

<ui_message_webview_url_scheme>://oauth_complete?status=<success|error>

This part is optional for OAuth, but highly recommended. If this is not set, the user will end on an MX page with a success or error message and will have to navigate back to your app manually. Make sure to pick a scheme that your app can respond to.

Postmessage events

A postMessage is an event-based protocol that allows partners to take action in their own codebase in response to events triggered within a widget’s user interface. They are intended specifically to allow a partner’s code and a widget user interface to work in concert, not to give a full picture of events happening on MX servers. PostMessage events should not be used for keeping data in sync between platforms.

Webhooks are a more reliable way of coordinating events between partner servers and MX servers, rather than the UI-oriented postMessages.

Events from MX will have mx, type, and metadata properties.

The mx field is provided as an easy way for partners to filter out postMessage events coming from MX.

The type field has the following schemea: mx/<entity|widget>/<event>. For example:

  • mx/account/created
  • mx/connect/institutionSelected
  • mx/transaction/updated

The type field identifies what the event represents at a high level. It is also useful for matching events for a given entity or widget, e.g, all account events will be prefixed with mx/account/*.

The metadata field is an object that has information related to the type that may be important, such as the account or transaction that was updated, the institution that was selected, etc. metadata objects will also have the user_guid and session_guid fields.

Example integration

1
2
3
4
5
6
7

function handleEvent(event) {
  if (event.data.mx) {
    // handle the mx post message using event.data.type and event.data.metadata.
  }
}

window.addEventListener('message', handleEvent)

Example event

1
2
3
4
5
6
7
8
9

const mxEvent = {
  mx: true,
  type: 'mx/account/created',
  metadata: {
    user_guid: 'USR-123',
    session_guid: 'ANS-123'
    // relevant data for the given type
  }
}

Connect loaded

Triggers when the Connect widget loads. It is often useful to know what “step” or view the user started on. The initial_step can be:

Value Definition
search The default initial step.
selectMember The initial step when configured with mode set to verification.
enterCreds The initial step when configured with current_institution_guid or current_member_guid, and updated_credentials set to true.
mfa The initial step when configured with current_member_guid and the member has encountered multi-factor authentication.
connected The initial step when configured with current_member_guid and the member is in a connected state.
loginError The initial step when configured with current_member_guid and the member is in an error state.

Connect loaded

1
2
3
4
5
6
7
8
9

{
  "type": "mx/connect/loaded",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "initial_step": "search"
  }
}

Enter credentials

Triggered when a user submits credentials for a given institution for the first time.

Enter credentials

1
2
3
4
5
6
7
8
9
10
11
12

{
  "type": "mx/connect/enterCredentials",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution": {
      "code": "mxbank",
      "guid": "INS-123"
    }
  }
}

Triggered when the end user searches for an institution. This is useful in determining what users are searching for.

Institution search

1
2
3
4
5
6
7
8
9

{
  "type": "mx/connect/institutionSearch",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "query": "MX Bank"
  }
}

Institution selected

Triggered when an end user selects an institution from the institution list.

Institution selected

1
2
3
4
5
6
7
8
9
10
11
12

{
  "type": "mx/connect/selectedInstitution",
  "mx": true,
  "metadata": {
    "code": "mxbank",
    "guid": "INS-123",
    "name": "MX Bank",
    "session_guid": "ANS-123",
    "url": "www.example.com",
    "user_guid": "USR-123"
  }
}

Member connected

Triggered when a member has successfully connected the account.

Member connected

1
2
3
4
5
6
7
8
9

{
  "type": "mx/connect/memberConnected",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Member connected, primary action selected

Triggered when the user selects the primary button on the connected step.

Member connected

1
2
3
4
5
6
7
8

{
  "type": "mx/connect/connected/primaryAction",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

Member deleted

Triggered when a member has been deleted in the widget.

Member deleted

1
2
3
4
5
6
7
8
9

{
  "type": "mx/connect/memberDeleted",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Member create error

Triggered when a member failed to get created when credentials were entered.

Member create error

1
2
3
4
5
6
7
8
9
10

{
  "type": "mx/connect/createMemberError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution_guid": "INS-123",
    "institution_code": "mxbank"
  }
}

Member status update

Triggered when a member’s connection status has changed while connecting. This is useful in determining the current connection status of the member.

Member status update

1
2
3
4
5
6
7
8
9
10

{
  "type": "mx/connect/memberStatusUpdate",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123",
    "connection_status": 6
  }
}

OAuth error

Triggered when the user lands on the OAuth error page. This is a general error message and could represent a problem with the OAuth provider or MX.

OAuth error

1
2
3
4
5
6
7
8
9

{
  "type": "mx/connect/oauthError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

OAuth requested

Triggered when the user navigates to the OAuth provider’s site. Note that the redirect does not happen in WebViews. The native app will need to use this postMessage to send the user to the URL contained in the metadata.

OAuth requested:

1
2
3
4
5
6
7
8
9

{
  "type": "mx/connect/oauthRequested",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "url": "https://something.com"
  }
}

Step change

Triggered when the end user changes from one “step” to another. This is useful for determining what transitions users are making. Possible step values can be:

Value Definition
search Where the users search for institutions.
selectMember Where the users can verify existing members when mode set to verification.
enterCreds Where the users enter credentials for a particular institution.
oauth Where the users go instead of enter credentials if the institution and client supports oauth.
mfa Where the users enter in MFA responses.
connecting Where the users go while the connection is being attempted.
existingMember Where the users land if they are trying to add a member they have previously added.
timeOut When the users have been connecting for more than 30 seconds without any updates to the member.
connected Where the user lands when they have successfully connected.
loginError Where the user lands when they have unsuccessfully connected due to user or system error.
error Where the user lands when the member create was unsuccessful due to user or system error.
verifyError Where the user lands when a verification job fails to start.
addManualAccount Where the users create manual accounts.

Connect step change

1
2
3
4
5
6
7
8
9
10

{
  "type": "mx/connect/stepChange",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "previous": "search",
    "current": "enterCreds"
  }
}

Submit MFA

Triggered when a user submits an MFA answer.

Submit MFA

1
2
3
4
5
6
7
8
9

{
  "type": "mx/connect/submitMFA",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Update credentials

Triggered when a user submits credentials while trying to update their existing credentials.

Update credentials

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "type": "mx/connect/updateCredentials",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123",
    "institution": {
      "code": "mxbank",
      "guid": "INS-123"
    }
  }
}

Widget load

Triggered when the app is loaded.

Widget load event

1
2
3
4

{
  "type": "mx/load",
  "mx": true
}

Widget ping

Used to keep the widget session alive.

Widget ping event

1
2
3
4
5
6
7
8

{
  "type": "mx/ping",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

Accounts

An account represents a financial account held by a financial institution, e.g., a user’s checking or savings account. 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.

Account fields

Field Data type Description
account_number String The account number associated with the account. This will typically be a masked or partial account number.
apr Decimal The annual percentage rate associated with the account.
apy Decimal The annual percentage yield associated with the account.
available_balance Decimal The balance that is available for use in asset accounts like checking and savings. PENDING transactions are typically taken into account with the available balance, but this may not always be the case.

available_balance will usually be a positive value for all account types, determined in the same way as the balance field.
available_credit Decimal The amount of credit available for use in liability accounts like credit cards and lines of credit. PENDING transactions are typically taken into account with available credit, but this may not always be the case.

available_credit will usually be a positive value for all account types, determined in the same way as the balance field.
balance Decimal The current balance of the account. PENDING transactions are typically not taken into account with the current balance, but this may not always be the case. This is the value used for the account balance displayed in MX UIs.

The balance will usually be a positive value for all account types. Asset-type accounts (CHECKING, SAVINGS, INVESTMENT) may have a negative balance if they are in overdraft. Debt-type accounts (CREDIT_CARD, LOAN, LINE_OF_CREDIT, MORTGAGE) may have a negative balance if they are overpaid.
cash_balance Decimal The cash balance of the account.
cash_surrender_value Decimal The sum of money paid to the policyholder or annuity holder in the event the policy is voluntarily terminated before it matures, or the insured event occurs.
created_at String The date and time at which the account was created on the MX Platform.
credit_limit Decimal The credit limit associated with the account.
currency_code String The three-character ISO 4217 currency code.
day_payment_is_due Integer The day of the month the payment is due. For example, the 14th is passed as 14.
death_benefit Integer The amount paid to the beneficiary of the account upon death of the account owner.
guid String The unique identifier for the account. Defined by MX.
holdings_value Decimal The value of the holdings associated with the account.
id String The unique partner-defined identifier for the account
imported_at String The date and time at which the account was last successfully aggregated and received data.
institution_code String A unique identifier for the institution associated with this account. Defined by MX.
insured_name String The name of the insured individual.
interest_rate Decimal The interest rate associated with the account.
is_closed Boolean This indicates whether an account has been closed.
is_hidden Boolean This indicates whether the account is hidden. Defaults to false.
last_payment_at String The date and time of the most recent payment on the account.
last_payment Decimal The amount of the most recent payment on the account.
loan_amount Decimal The amount of the loan associated with the account.
matures_on String The date on which the account matures.
member_guid String The unique identifier for the member associated with the account. Defined by MX.
member_id String The unique, partner-defined, identifier for the member associated with this account.
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.
metadata String Additional information a partner can store on the account.
minimum_balance Decimal The minimum balance associated with the account.
minimum_payment Decimal The minimum payment required for an account. This can apply to any debt account.
name String The human-readable name for the account.
nickname String An alternate name for the account.
original_balance Decimal The original balance associated with the account. This will always be positive.
pay_out_amount Decimal The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy.
payment_due_at String The date and time at which the next payment is due on the account.
payoff_balance Decimal The payoff balance for a debt account. This will normally be a positive number.
premium_amount Decimal The insurance policy’s premium amount.
routing_number String The routing number for the account.
started_on String The date on which a debt account was started.
subtype String The account’s subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY.
total_account_value Decimal The total value of the account.
type String The general or parent type of the account.
updated_at String The date and time at which the account was most recently updated.
user_guid String The unique identifier for the user associated with the account. Defined by MX.
user_id String The unique, partner-defined, identifier for the user associated with this account.

Account types and subtypes

Parent types
ANY (not provided by data partner or invalid number provided)
CHECKING
SAVINGS
LOAN
CREDIT_CARD
INVESTMENT
LINE_OF_CREDIT
MORTGAGE
PROPERTY
CASH
INSURANCE
PREPAID
Subtype Parent type
MONEY_MARKET SAVINGS
CERTIFICATE_OF_DEPOSIT SAVINGS
AUTO LOAN
STUDENT LOAN
SMALL_BUSINESS LOAN
PERSONAL LOAN
PERSONAL_WITH_COLLATERAL LOAN
HOME_EQUITY LOAN
PLAN_401_K INVESTMENT
PLAN_403_B INVESTMENT
PLAN_529 INVESTMENT
IRA INVESTMENT
ROLLOVER_IRA INVESTMENT
ROTH_IRA INVESTMENT
TAXABLE INVESTMENT
NON_TAXABLE INVESTMENT
BROKERAGE INVESTMENT
TRUST INVESTMENT
UNIFORM_GIFTS_TO_MINORS_ACT INVESTMENT
PLAN_457 INVESTMENT
PENSION INVESTMENT
EMPLOYEE_STOCK_OWNERSHIP_PLAN INVESTMENT
SIMPLIFIED_EMPLOYEE_PENSION INVESTMENT
SIMPLE_IRA INVESTMENT
BOAT LOAN
POWERSPORTS LOAN
RV LOAN
HELOC LOAN
PLAN_ROTH_401_K INVESTMENT
FIXED_ANNUITY INVESTMENT
VARIABLE_ANNUITY INVESTMENT
VEHICLE_INSURANCE INSURANCE
DISABILITY INSURANCE
HEALTH INSURANCE
LONG_TERM_CARE INSURANCE
PROPERTY_AND_CASUALTY INSURANCE
UNIVERSAL_LIFE INSURANCE
TERM_LIFE INSURANCE
WHOLE_LIFE INSURANCE
ACCIDENTAL_DEATH_AND_DISMEMBERMENT INSURANCE
VARIABLE_UNIVERSAL_LIFE INSURANCE
HSA INVESTMENT
TAX_FREE_SAVINGS_ACCOUNT INVESTMENT
INDIVIDUAL INVESTMENT
REGISTERED_RETIREMENT_INCOME_FUND INVESTMENT
CASH_MANAGEMENT_ACCOUNT INVESTMENT
EMPLOYEE_STOCK_PURCHASE_PLAN INVESTMENT
REGISTERED_EDUCATION_SAVINGS_PLAN INVESTMENT
PROFIT_SHARING_PLAN INVESTMENT
UNIFORM_TRANSFER_TO_MINORS_ACT INVESTMENT
PLAN_401_A INVESTMENT
SARSEP_IRA INVESTMENT
FIXED_ANNUITY_TRADITIONAL_IRA INVESTMENT
VARIABLE_ANNUITY_TRADITIONAL_IRA INVESTMENT
SEPP_IRA INVESTMENT
INHERITED_TRADITIONAL_IRA INVESTMENT
FIXED_ANNUITY_ROTH_IRA INVESTMENT
VARIABLE_ANNUITY_ROTH_IRA INVESTMENT
INHERITED_ROTH_IRA INVESTMENT
COVERDELL INVESTMENT
ADVISORY_ACCOUNT INVESTMENT
BROKERAGE_MARGIN INVESTMENT
CHARITABLE_GIFT_ACCOUNT INVESTMENT
CHURCH_ACCOUNT INVESTMENT
CONSERVATORSHIP INVESTMENT
CUSTODIAL INVESTMENT
DEFINED_BENEFIT_PLAN INVESTMENT
DEFINED_CONTRIBUTION_PLAN INVESTMENT
EDUCATIONAL INVESTMENT
ESTATE INVESTMENT
EXECUTOR INVESTMENT
GROUP_RETIREMENT_SAVINGS_PLAN INVESTMENT
GUARANTEED_INVESTMENT_CERTIFICATE INVESTMENT
HRA INVESTMENT
INDEXED_ANNUITY INVESTMENT
INVESTMENT_CLUB INVESTMENT
IRREVOCABLE_TRUST INVESTMENT
JOINT_TENANTS_BY_ENTIRITY INVESTMENT
JOINT_TENANTS_COMMUNITY_PROPERTY INVESTMENT
JOINT_TENANTS_IN_COMMON INVESTMENT
JOINT_TENANTS_WITH_RIGHTS_OF_SURVIVORSHIP INVESTMENT
KEOUGH_PLAN INVESTMENT
LIFE_INCOME_FUND INVESTMENT
LIVING_TRUST INVESTMENT
LOCKED_IN_RETIREMENT_ACCOUNT INVESTMENT
LOCKED_IN_RETIREMENT_INVESTMENT_FUND INVESTMENT
LOCKED_IN_RETIREMENT_SAVINGS_ACCOUNT INVESTMENT
MONEY_PURCHASE_PLAN INVESTMENT
PARTNERSHIP INVESTMENT
PLAN_409_A INVESTMENT
PLAN_ROTH_403_B INVESTMENT
REGISTERED_DISABILITY_SAVINGS_PLAN INVESTMENT
REGISTERED_LOCKED_IN_SAVINGS_PLAN INVESTMENT
REGISTERED_PENSION_PLAN INVESTMENT
REGISTERED_RETIREMENT_SAVINGS_PLAN INVESTMENT
REVOCABLE_TRUST INVESTMENT
ROTH_CONVERSION INVESTMENT
SOLE_PROPRIETORSHIP INVESTMENT
SPOUSAL_IRA INVESTMENT
SPOUSAL_ROTH_IRA INVESTMENT
TESTAMENTARY_TRUST INVESTMENT
THRIFT_SAVINGS_PLAN INVESTMENT
INHERITED_ANNUITY INVESTMENT
CORPORATE_ACCOUNT INVESTMENT
LIMITED_LIABILITY_ACCOUNT INVESTMENT

List accounts

This endpoint returns a list of all the accounts associated with the specified user.

Endpoint:

GET /users/{user_guid}/accounts

1
2
3

curl -X GET https://int-api.mx.com/users/USR-11a448aa-5e7b-70db-45d6-d6927092043e/accounts \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

{
  "accounts": [
    {
      "account_number": "5366",
      "apr": null,
      "apy": null,
      "available_balance": null,
      "available_credit": 327.01,
      "balance": 1872.99,
      "cash_balance": null,
      "cash_surrender_value": null,
      "created_at": "2020-08-04T21:27:47Z",
      "credit_limit": null,
      "currency_code": "USD",
      "day_payment_is_due": null,
      "death_benefit": null,
      "guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f3f756",
      "holdings_value": null,
      "id": "1041424581",
      "imported_at": "2021-08-01T12:00:47Z",
      "institution_code": "chase",
      "insured_name": null,
      "interest_rate": null,
      "is_closed": false,
      "is_hidden": false,
      "last_payment": null,
      "last_payment_at": null,
      "loan_amount": null,
      "matures_on": null,
      "member_guid": "MBR-0b2121f5-bf4f-4244-a697-ca5925a325a1",
      "member_id": "M-1260571",
      "member_is_managed_by_user": true,
      "metadata": null,
      "minimum_balance": null,
      "minimum_payment": null,
      "name": "CREDIT CARD",
      "nickname": null,
      "original_balance": null,
      "pay_out_amount": null,
      "payment_due_at": null,
      "payoff_balance": null,
      "premium_amount": null,
      "routing_number": null,
      "started_on": null,
      "subtype": "NONE",
      "total_account_value": null,
      "type": "CREDIT_CARD",
      "updated_at": "2021-01-15T17:09:09Z",
      "user_guid": "USR-11a448aa-5e7b-70db-45d6-d6927092043e",
      "user_id": "U-107895"
    },
•••
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 8,
    "total_pages": 1
  }
}

Read account

This endpoint returns the specified account resource.

Endpoint:

GET /users/{user_guid}/accounts/{account_guid}

1
2
3

curl -X GET https://int-api.mx.com/users/USR-11a448aa-5e7b-70db-45d6-d6927092043e/accounts/ACT-fcdfc4bc-bbff-4f1e-b5d1-35197f \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

{
  "account": {
    "account_number": "5366",
    "apr": null,
    "apy": null,
    "available_balance": null,
    "available_credit": 327.01,
    "balance": 1872.99,
    "cash_balance": null,
    "cash_surrender_value": null,
    "created_at": "2020-08-04T21:27:47Z",
    "credit_limit": null,
    "currency_code": "USD",
    "day_payment_is_due": null,
    "death_benefit": null,
    "guid": "ACT-82a93692-f756-534f-9b2e-ad10534f9b2e",
    "holdings_value": null,
    "id": "104055120",
    "imported_at": "2021-08-01T12:00:47Z",
    "institution_code": "chase",
    "insured_name": null,
    "interest_rate": null,
    "is_closed": false,
    "is_hidden": false,
    "last_payment": null,
    "last_payment_at": null,
    "loan_amount": null,
    "matures_on": null,
    "member_guid": "MBR-0b2121f5-bf4f-4244-a697-cac64244a697",
    "member_id": "1505009123",
    "member_is_managed_by_user": true,
    "metadata": null,
    "minimum_balance": null,
    "minimum_payment": null,
    "name": "CREDIT CARD",
    "nickname": null,
    "original_balance": null,
    "pay_out_amount": null,
    "payment_due_at": null,
    "payoff_balance": null,
    "premium_amount": null,
    "routing_number": null,
    "started_on": null,
    "subtype": "NONE",
    "total_account_value": null,
    "type": "CREDIT_CARD",
    "updated_at": "2021-01-15T17:09:09Z",
    "user_guid": "USR-11a448aa-5e7b-70db-45d6-d6927092043e",
    "user_id": "U-107895"
  }
}

Update account

This endpoint allows you to update certain attributes of an account resource.

Parameters

Field name Data type Required?
is_hidden Boolean No

Endpoint:

PUT /users/{user_guid}/members/{member_guid}/accounts/{account_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06c11141024/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/accounts/ACT-82a63692-f766-534f-9b2e-ad12a0b7001a' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -d '{
        "account": {
          "is_hidden": true
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

{
  "account": {
    "account_number": "5366",
    "apr": null,
    "apy": null,
    "available_balance": null,
    "available_credit": 327.01,
    "balance": 1872.99,
    "cash_balance": null,
    "cash_surrender_value": null,
    "created_at": "2020-08-04T21:27:47Z",
    "credit_limit": null,
    "currency_code": "USD",
    "day_payment_is_due": null,
    "death_benefit": null,
    "guid": "ACT-82a63692-f766-534f-9b2e-ad12a0b7001a",
    "holdings_value": null,
    "id": "104434698",
    "imported_at": "2021-08-01T12:00:47Z",
    "institution_code": "chase",
    "insured_name": null,
    "interest_rate": null,
    "is_closed": false,
    "is_hidden": true,
    "last_payment": null,
    "last_payment_at": null,
    "loan_amount": null,
    "matures_on": null,
    "member_guid": "MBR-0b2321f5-bf4f-4224-a637-cac69fa051b",
    "member_id": "104064688356",
    "member_is_managed_by_user": true,
    "metadata": null,
    "minimum_balance": null,
    "minimum_payment": null,
    "name": "CREDIT CARD",
    "nickname": null,
    "original_balance": null,
    "pay_out_amount": null,
    "payment_due_at": null,
    "payoff_balance": null,
    "premium_amount": null,
    "routing_number": null,
    "started_on": null,
    "subtype": "NONE",
    "total_account_value": null,
    "type": "CREDIT_CARD",
    "updated_at": "2021-01-15T17:09:09Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06c11141024",
    "user_id": "104001234"
  }
}

Institutions

An institution represents a financial institution like Chase, Wells Fargo, or Mountain America Credit Union.

It’s important to point out that many real-world financial institutions will actually have several different institution objects within the MX Platform API. This is because, for example, the banking and mortgage divisions of Wells Fargo may use separate online systems for accessing customer data, both of which may be different from the credit card division’s system, etc.

Institution fields

Field Data type Description
code String A unique identifier for each institution, defined by MX.
medium_logo_url String The URL for a 100px X 100px logo for each institution. A generic logo is returned for institutions that don’t have one.
name String An easy-to-read name for an institution, e.g., “Chase Bank” or “Wells Fargo Bank.”
small_logo_url String The URL for a 50px X 50px logo for each institution. A generic logo is returned for institutions that don’t have one.
supports_account_identification Boolean This indicates whether the institution supports account identification.
supports_account_statement Boolean This indicates whether the institution provides access to account statements.
supports_account_verification Boolean This indicates whether the institution supports account verification.
supports_oauth Boolean This indicates whether the institution supports OAuth authentication.
supports_transaction_history Boolean This indicates whether the institution allows access to up to 24 months of transaction data.
url String The URL for particular institution’s website , e.g., www.chase.com.

List favorites

This endpoint returns a paginated list containing institutions that have been set as the partner’s favorites, sorted by popularity.

Please contact MX to set a list of favorites.

Endpoint:

GET /institutions/favorites

1
2
3

curl -X GET https://int-api.mx.com/institutions/favorites \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
  "institutions": [
    {
      "code": "52726",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "Washington Federal",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": null,
      "supports_account_statement": null,
      "supports_account_verification": true,
      "supports_oauth": false,
      "supports_transaction_history": null,
      "url": "www.washingtonfederal.com"
    },
    {
      "code": "capital_one",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "Capital One",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": null,
      "supports_account_statement": null,
      "supports_account_verification": false,
      "supports_oauth": false,
      "supports_transaction_history": null,
      "url": "http://www.capitalone.com"
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 130,
    "total_pages": 6
}
}

List institution-required credentials

Endpoint:

GET /institutions/{institution_code}/credentials

1
2
3

curl -X GET https://int-api.mx.com/institutions/mxbank/credentials \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "credentials": [
    {
      "display_order": 1,
      "field_name": "LOGIN",
      "field_type": "LOGIN",
      "guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
      "label": "Username"
    },
    {
      "display_order": 2,
      "field_name": "PASSWORD",
      "field_type": "PASSWORD",
      "guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
      "label": "Password"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

List institutions

This endpoint returns a list of institutions based on the specified search term or parameter.

Query parameters

Parameter Results
name={string} Only institutions whose name contains the appended string will be returned.
supports_account_identification=true Only institutions which support identity will be returned.
supports_account_statement=true Only institutions which offer access to account statements will be returned.
supports_account_verification=true Only institutions which support account verification will be returned.
supports_transaction_history=true Only institutions which offer an extended transaction history will be returned.

Endpoint:

GET /institutions

1
2
3

curl -X GET https://int-api.mx.com/institutions \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
  "institutions": [
    {
      "code": "5426",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "Test",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": false,
      "supports_account_statement": false,
      "supports_account_verification": false,
      "supports_oauth": false,
      "supports_transaction_history": false,
      "url": "testbankformoneydesktop.com"
    },
    {
      "code": "50025",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-a4c142b7-9d52-e9e9-e464-4d00eaa81f76_100x100.png",
      "name": "Franklin-Oil Region CU",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-a4c142b7-9d52-e9e9-e464-4d00eaa81f76_50x50.png",
      "supports_account_identification": false,
      "supports_account_statement": false,
      "supports_account_verification": false,
      "supports_oauth": false,
      "supports_transaction_history": false,
      "url": "www.franklincreditunion.com"
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 130,
    "total_pages": 6
}
}

Example request with query parameters

1
2
3

curl -X GET https://int-api.mx.com/institutions?name=chase \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
    "institutions": [
        {
            "code": "71426",
            "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-7cf00356-2c62-3764-a2bf-6451477d5117_100x100.png",
            "name": "Chase Bank",
            "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-7cf00356-2c62-3764-a2bf-6451477d5117_50x50.png",
            "supports_account_identification": false,
            "supports_account_statement": false,
            "supports_account_verification": true,
            "supports_oauth": false,
            "supports_transaction_history": false,
            "url": "http://www.chase.com/"
        },
        {
            "code": "f2fe7f27-7005-46ba-b528-20e09b5152a4",
            "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
            "name": "Centre @ Riverchase",
            "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
            "supports_account_identification": false,
            "supports_account_statement": false,
            "supports_account_verification": false,
            "supports_oauth": false,
            "supports_transaction_history": false,
            "url": "https://www.doxo.com/info/centre-at-riverchase"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 25,
        "total_entries": 2,
        "total_pages": 1
    }
}

Read institution

This endpoint returns information about the institution specified by institution_code.

Endpoint:

GET /institutions/{institution_code}

1
2
3

curl -X GET https://int-api.mx.com/institutions/50025 \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "institution": {
    "code": "50025",
    "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-a4c142b7-9d52-e9e9-e464-4d00eaa81f76_100x100.png",
    "name": "Franklin-Oil Region CU",
    "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-a4c142b7-9d52-e9e9-e464-4d00eaa81f76_50x50.png",
    "supports_account_identification": false,
    "supports_account_statement": false,
    "supports_account_verification": false,
    "supports_oauth": false,
    "supports_transaction_history": false,
    "url": "www.franklincreditunion.com"
  }
}

Members

A member represents the relationship between a user and an institution, and creating one is how you connect one to the other. Multiple members may be attached to a single user, e.g., one member for their bank, another for their mortgage provider, another for their credit card provider, etc.

Member fields

Field Data type Definition
aggregated_at String The date and time the most recent aggregation-type job was started, given in ISO 8601 format with a time component. A job will automatically be started when a member is created or its credentials are updated, unless the skip_aggregation parameter is used. Jobs can also be started via manual aggregations, background aggregations, API endpoints, or when opening an MX widget. A job can be a normal aggregation, or a premium job such as identification, verification, fetching statements, or fetching an extended transaction history.

If a member is deleted and then re-created with the skip_aggregation parameter set to true or if it is re-created within the throttle window (typically three hours), the previous value will be returned.
connection_status String This indicates the state of a member’s aggregation. See member connection statuses for more information.
guid String The unique identifier for the member. Defined by MX.
id String The partner-defined unique identifier for the member.
institution_code String The unique identifier for the institution associated with the member. Defined by MX.
is_being_aggregated Boolean This indicates whether the member was being aggregated at the time of the request.
is_managed_by_user String 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.
is_oauth Boolean This indicates whether the member uses OAuth to authenticate. Defaults to false.
metadata String Additional information you can store on this member.
name String The name of the member.
successfully_aggregated_at String The date and time the member was last successfully aggregated.
user_guid String The unique identifier for the user associated with the member. Defined by MX.
user_id String The unique partner-defined identifier for the user associated with the member.

Connection statuses

Integer value Status Definition Next steps End-user message
null null The member exists but does not have credentials. A member that does not aggregate (e.g., a manual member) will always have this status. None. None.
0 CREATED The member is new and has not yet been aggregated. Aggregate the member once the end user logs in; poll for a status update. Connecting to {…} …
1 PREVENTED MX is preventing aggregation until the member’s credentials have been updated. Display end-user message; after end user has updated their credentials, aggregate again. The last 3 attempts to connect have failed. Please re-enter your credentials to continue importing data.
2 DENIED The credentials provided for the member were invalid. Display end-user message; after end user has updated their credentials, aggregate again. The credentials entered do not match your credentials at this institution. Please re-enter your credentials to continue importing data.
3 CHALLENGED The member has been challenged by multi-factor authentication. Display end-user message; follow MFA pathway; after the user answers MFA, poll for a status update. To authenticate your connection to {…}, please answer the following challenge(s).
4 REJECTED An MFA challenge was answered incorrectly. Display end-user message; another challenge may follow or aggregation may need to be restarted. The answer or answers provided were incorrect. Please try again.
5 LOCKED The financial institution is preventing authentication. The end user must contact the financial institution. Display end-user message. Your account is locked. Please log in to the appropriate website for {…} and follow the steps to resolve the issue.
6 CONNECTED The member was successfully authenticated and data is now aggregating. Display the account as having been connected. Connected to […] …
7 IMPEDED The end user’s attention is required at their online banking institution, e.g., there is a marketing message that must be viewed, terms and conditions that must be accepted, etc. Display end-user message. Your attention is needed at this institution’s website. Please log in to the appropriate website for {…} and follow the steps to resolve the issue.
8 RECONNECTED The member has been migrated to a new data source and aggregation is likely to trigger one-time password MFA. MX will not perform background aggregation in order to avoid unnecessarily disruptive texts, emails, etc. The member must be re-aggregated in the foreground with the end user present. Aggregate the member once the end user logs in; poll for a status update. Reconnecting to {…} …
9 DEGRADED Aggregation has failed at least three times within a short period of time. Display end-user message. We are upgrading this connection. Please try again later.
10 DISCONNECTED Aggregation has failed at least three times and has not succeeded for at least two weeks. Display end-user message. It looks like your data from {…} cannot be imported. We are working to resolve the issue.
11 DISCONTINUED The connection to this financial institution is no longer available. Display end-user message. Connections to this institution are no longer supported. You may create a manual account and use manual transactions to track data for this account.
12 CLOSED The end user, MX, the client, or a partner has marked the member as closed. Display end-user message. This connection has been closed. You may track this account manually. If reopened, you may connect the institution again.
13 DELAYED Aggregating the member has taken longer than expected and it has not yet been connected. Display end-user message; poll for a status update. Importing your data from {…} may take a while. Please check back later.
14 FAILED Aggregation failed without being connected. Display end-user message; try aggregating again later. There was a problem validating your credentials with {…}. Please try again later.
15 UPDATED The member has been updated — i.e., credentials have been updated — but it has not yet been connected. Aggregate the member once the end user logs in; poll for a status update. Connecting to {…} …
16 DISABLED Aggregation has been momentarily paused, but the member is still connected. Display end-user message. Importing data from this institution has been disabled. Please contact us if you believe it has been disabled in error.
17 IMPORTED MX does not have credentials and will not try to aggregate the member until the end user provides credentials. Display end-user message; re-aggregate after the end user updates credentials. You must re-authenticate before your data can be imported. Please enter your credentials for {…}.
18 RESUMED The answer to an MFA challenge was received, but it is not yet clear whether it was correct. Poll for a status update. Connecting to {…} …
19 EXPIRED The MFA answer was not provided within the time allotted by the financial institution. Display end-user message; re-aggregate the member if the end user initiates it. The answer or answers were not provided in time. Please try again.
20 IMPAIRED The member is missing some or all credentials needed in order to connect. Display end-user message; re-aggregate after the end user updates credentials. You must re-authenticate before your data can be imported. Please enter your credentials for {…}.
21 PENDING The member is using OAuth to authenticate credentials and still needs to go through the financial institution’s OAuth process. A PENDING status will appear only on members less than one hour old with is_oauth: true. Members that stay PENDING longer than one hour will be deleted by MX. Redirect the end user to the oauth_window_uri provided in the create member response, or request one through the generate OAuth window URI endpoint. None.

Aggregate member

Calling this endpoint initiates an aggregation event for the member. This gathers the latest account and transaction data from the connected institution. If this data has recently been updated, MX may not initiate an aggregation event.

If a standard aggregation is already running, a 202 Accepted status will be returned. If another aggregation-type process is already running — like verification or extended transaction history — a 409 Conflict will be returned.

Endpoint:

POST /users/{user_guid}/members/{member_guid}/aggregate

1
2
3
4

curl -i -X POST 'https://int-api.mx.com/users/USR-1234/members/MBR-5678/aggregate' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": "2020-04-29T20:40:07Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": "2019-08-08T16:17:51Z",
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

Check balances

This endpoint operates much like the aggregate member endpoint except that it gathers only account balance information; it does not gather any transaction data.

If an account balance aggregation is already running, a 202 Accepted status will be returned. If another aggregation-type process is already running — like verification or extended transaction history — a 409 Conflict will be returned.

Repeated calls to this endpoint for the same member can only be made at intervals greater that two hours. If made more frequently, a 429 Too Many Requests status will be returned.

Endpoint:

POST /users/{user_guid}/members/{member_guid}/check_balance

1
2
3
4

curl -i -X POST 'https://int-api.mx.com/users/USR-1234/members/MBR-5678/check_balance' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": "2020-04-29T20:40:07Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": "2019-08-08T16:17:51Z",
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

Create member

This endpoint allows you to create a new member. The API supports both standard members and OAuth members.

Standard members are created with the required parameters credentials and institution_code.

When creating a standard member, you’ll need to include the correct type of credential required by the financial institution, with values provided by the end user. You can find out which credential type is required with the list institution-required credentials endpoint.

Once you successfully create a standard member, MX will immediately validate the provided credentials and attempt to aggregate data for accounts and transactions. You can prevent this automatic aggregation by setting the skip_aggregation parameter to true.

OAuth members can only be created with institutions that support it. OAuth members require no credentials, but do require you to set the is_oauth parameter to true.

OAuth members will be created with a connection status of PENDING; a one-time use redirect URI will be provided in the oauth_window_uri field of the response. Making a separate request to the oauth_window_uri will then take the end user to the registered OAuth application where they can provide credentials and choose what data to share with MX.

After completing the OAuth process, aggregation automatically will begin and the connection status will be updated — unless the skip_aggregation parameter was set to true.

Parameter Data type Description Required?
background_aggregation_is_disabled Boolean When set to true, background aggregation will be disabled for this member. No
credentials Array The credentials endpoint for the requested institution will give you a list of all the credentials required to create a member for a given institution. Each required credential will need to be included within this array. Yes
id String The unique partner-defined identifier for the member. No
institution_code String The unique code for the institution to which the member will connect. Defined by MX. Yes
metadata String Additional information you can store on this member. No
is_oauth Boolean This indicates whether the member uses OAuth authentication or not. OAuth members do not require credentials when being created; instead, the member is created with a PENDING status and the response to the request will contain the oauth_window_uri attribute; the end user authenticates credentials with OAuth. No
referral_source String Must be either BROWSER or APP depending on the implementation. Defaults to BROWSER. This field should not be nested under the member when given in a request body; it can also be sent as a query parameter to the the generate OAuth window URI endpoint. No
skip_aggregation Boolean Setting this parameter to true will prevent the member from automatically aggregating when it is created. No
ui_message_webview_url_scheme String A scheme for routing the user back to the application state they were previously in. This field should not be nested under the member when given in a request body; it can also be sent as a query parameter to the the generate OAuth window URI endpoint. No

Endpoint:

POST /users/{user_guid}/members

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "credentials": [
          {
            "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
            "value": "ExampleUsername"
          },
          {
            "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
            "value": "Pa$$vv@Rd"
          }
        ],
        "institution_code": "mxbank"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

Example request with is_oauth

1
2
3
4
5
6
7
8
9
10
11
12
13

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v2+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "institution_code": "mx_bank_oauth",
        "is_oauth": true,
        "metadata": "Additional information"
      },
      "referral_source": "APP",
      "ui_message_webview_url_scheme": "myapp"
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "member": {
    "aggregated_at": null,
    "connection_status": "PENDING",
    "guid": "MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f",
    "id": null,
    "institution_code": "mx_bank_oauth",
    "is_being_aggregated": false,
    "is_managed_by_user": true,
    "is_oauth": true,
    "metadata": "Additional information",
    "name": "MX Bank (Oauth)",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": null,
  }
}

Delete member

Making a request to this endpoint will permanently delete the specified member.

A successful response will have the status 204 No Content.

Endpoint:

DELETE /users/{user_guid}/members/{member_guid}

1
2
3

curl -i -X DELETE https://int-api.mx.com/users/USR-1234/members/MBR-4567 \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

Generate an OAuth window URI

This endpoint will generate an oauth_window_uri for the specified member.

Generating a new oauth_window_uri is necessary in order to send the end user through the OAuth process again. There are several situations where you might want to do this. Below are a few examples:

  • A previous attempt at OAuth failed — for instance if the end user closed the OAuth window before completing the process.
  • The financial institution has revoked a previous OAuth token or the token has expired.

The member in question must be connected to an institution which supports OAuth. If the institution does not support OAuth, a 400 Bad Request error will be returned with the message Member cannot use OAuth.

Query parameters

Parameter Data type Description Required?
referral_source String Must be either BROWSER or APP depending on the implementation. Defaults to BROWSER. No
ui_message_webview_url_scheme String A scheme for routing the user back to the application state they were previously in. No
skip_aggregation Boolean Setting this parameter to true will prevent the member from automatically aggregating after being redirected from the authorization page. No

Endpoint:

GET /users/{user_guid}/members/{member_guid}/oauth_window_uri

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/oauth_window_uri' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v2+json'

1
2
3
4
5
6

{
    "member": {
        "guid": "MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f",
        "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/zgknnw5k7dmztn2njmwlgz574mZlnft6vdrv7kzn9ptj325th6c5p0w6c7j83Ap1bqg01mhsr1bqjgf2fry3ly9wff497c6fcczbyrfgj7s39cygw95Akl7vlpmcAy2kmvh1mlkytg7jA1z3vnw1w3zx2r1wt65s6f6r3ryqqrysl9qA1kr6cAj6vhr1zl325Azz6hx52j1ll3vwbvvbv5xzy7d6csplyw25brA7147vAfq29ArjjAj4qmc6r6h457hkcj2946m0kjp2xzpkz6hz55lsp3Avmdb8dsq4xzqmzzqk68s6bp5tj9jsskw4wvcb95vm4fwh9w8phgp67hfj2flrtwcy5bxbtk74?skip_aggregation=false"
    }
}

List member challenges

Use this endpoint for information on what multi-factor authentication challenges need to be answered in order to aggregate a member.

The exact fields returned in the challenges object will differ depending on the type of challenge that has been issued. For instance, a challenge with the type OPTIONS includes the options array, whereas one with the type TEXT does not.

If the aggregation is not challenged, i.e., the member does not have a connection status of CHALLENGED, then code 204 No Content will be returned.

If the aggregation has been challenged, i.e., the member does have a connection status of CHALLENGED, then code 200 OK will be returned along with the corresponding challenges.

Challenge fields

Field Name Data type Description
field_name String A non-unique identifier for the question.
guid String A unique identifier for the challenge, defined by MX.
image_data String This field contains image data encoded as a base64 string. It will only be present when the challenge type is IMAGE_DATA.
image_options Array For challenge type IMAGE_OPTIONS, this field represents an array of choices. It will only be present when the challenge type is IMAGE_OPTIONS.
label String A readable question that is presented to the user.
options Array For challenge type OPTIONS, this field represents an array of choices. It will only be present when the challenge type is OPTIONS.
type String The type of challenge. Supported types include TEXT, OPTIONS, TOKEN, IMAGE_DATA, IMAGE_OPTIONS.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/challenges

1
2
3

curl -X GET https://int-api.mx.com/users/USR-1234/members/MBR-1234/challenges \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

{
  "challenges": [
    {
      "field_name": "text",
      "guid": "CRD-123",
      "label": "What is your name",
      "type": "TEXT"
    },
    {
      "field_name": "text",
      "guid": "CRD-456",
      "label": "What is your favorite color?",
      "options": [
        {
          "label": "Blue",
          "value": 1
        },
        {
          "label": "Red",
          "value": 2
        }
      ],
      "type": "OPTIONS"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

List member credentials

This endpoint returns an array which contains information on every non-MFA credential associated with a specific member.

Credential fields

Field Data type Description
display_order Integer The order in which the credential should be displayed to the end user; lower numbers should be displayed first.
field_name String The name of the credential field for the institution, e.g., “LOGIN”.
field_type String The type of field for this credential, e.g., TEXT, OPTIONS, TOKEN.
guid String A unique identifier for the credential. Defined by MX.
label String A label for the credential, intended to be readable by the end user, e.g., Username.

Credential field types

Field type integer Field type string
0 TEXT
1 PASSWORD
2 OPTIONS
3 LOGIN
12 TOKEN
13 IMAGE_DATA
14 IMAGE_OPTIONS

Endpoint:

GET /users/{user_guid}/members/{member_guid}/credentials

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/credentials' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "credentials": [
    {
      "display_order": 1,
      "field_name": "LOGIN",
      "field_type": "LOGIN",
      "guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
      "label": "Username"
    },
    {
      "display_order": 2,
      "field_name": "PASSWORD",
      "field_type": "PASSWORD",
      "guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
      "label": "Password"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

List members

This endpoint returns a list of all the members that belong to the specified user.

Endpoint:

GET /users/{user_guid}/members

1
2
3

curl -X GET https://int-api.mx.com/users/USR-1234/members \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

{
  "members": [
    {
      "aggregated_at": "2019-12-03T18:10:22Z",
      "connection_status": "CONNECTED",
      "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
      "id": null,
      "institution_code": "mxbank",
      "is_being_aggregated": false,
      "is_managed_by_user": true,
      "is_oauth": false,
      "metadata": null,
      "name": "MX Bank",
      "successfully_aggregated_at": "2019-08-08T16:17:51Z",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
      "user_id": null,
    },
    {
      "aggregated_at": "2019-12-03T18:10:22Z",
      "connection_status": "FAILED",
      "guid": "MBR-61bfd52c-2e3c-44ef-b747-20797a6f9dc0",
      "id": null,
      "institution_code": "capital_one",
      "is_being_aggregated": false,
      "is_managed_by_user": true,
      "is_oauth": false,
      "metadata": null,
      "name": "Capital One ",
      "successfully_aggregated_at": null,
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
      "user_id": null
    },
    {
      "aggregated_at": "2019-12-03T18:10:23Z",
      "connection_status": "DEGRADED",
      "guid": "MBR-98ae3e6e-1623-4471-add6-b464bdb4a900",
      "id": null,
      "institution_code": "paypal",
      "is_being_aggregated": false,
      "is_managed_by_user": true,
      "is_oauth": false,
      "metadata": null,
      "name": "PayPal",
      "successfully_aggregated_at": null,
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
      "user_id": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 3,
    "total_pages": 1
  }
}

Read member

This endpoint returns information about the specified member.

Endpoint:

GET /users/{user_guid}/members/{member_guid}

1
2
3

curl -X GET https://int-api.mx.com/users/USR-1234/members/MBR-4567 \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": "2019-12-03T18:10:22Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": false,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": "2019-08-08T16:17:51Z",
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

Read member status

This endpoint returns information about the member’s connection to a financial institution, including crucial information about aggregation.

The fields returned here should be interpreted together to get a picture of what is happening with the member.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/status

1
2
3

curl -i 'https://int-api.mx.com/users/USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10

{
  "member": {
    "aggregated_at": "2020-05-07T22:01:00Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2020-05-07T22:01:25Z"
  }
}

Resume aggregation

This endpoint answers the challenges given when a member has been challenged by multi-factor authentication.

Endpoint:

PUT /users/{user_guid}/members/{member_guid}/resume

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/resume' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "challenges": [
          {
            "guid": "CRD-2378634-33ub5bhk54kjb",
            "value": "user-entered-value"
          },
          {
            "guid": "CRD-iu34yu39-98745jb45jb-d987r6",
            "value": "user-entered-value"
          }
        ]
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "member": {
    "aggregated_at": "2020-04-29T20:40:07Z",
    "connection_status": "RESUMED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-426501cf7ba5",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": "2019-08-08T16:17:51Z",
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

Update member

Use this endpoint to update certain attributes of the specified member. To get a list of the required credentials for a member, use the list member credentials endpoint.

Parameter Data type Description Required?
background_aggregation_is_disabled Boolean This indicates whether background aggregation should be disabled for the member. No
credentials Array The credentials that you wish to update for this member. No
id String The unique partner-definite identifier for the member. No
metadata String Additional information you can store on this member. No
skip_aggregation Boolean Setting this parameter to true will prevent the member from automatically aggregating when it is created. No

Endpoint:

PUT /users/{user_guid}/members/{member_guid}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

curl -i -X PUT 'https://int-api.mx.com/users/USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "credentials": [
          {
            "guid": "CRD-598ec8d4-6200-8cda-345d-3dbb5fc17716",
            "value": "updated-username"
          },
          {
            "guid": "CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f",
            "value": "updated-password"
          }
        ],
        "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-16\"}"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": "2020-04-29T20:40:07Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": "2019-08-08T16:17:51Z",
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

Transactions

A transaction represents 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, etc. Each transaction belongs to only one account.

Transaction 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.
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, e.g., “Sam’s Club,” “Johnny’s 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_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 indicates whether a transaction is a recurring credit or debit.
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 (e.g. 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 (e.g. Rio de Janeiro’s longitude is -43.2075000 and Tokyo’s longitude 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 categories

Categories

* Auto & Transport
  * Auto Insurance
  * Auto Payment
  * Gas
  * Parking
  * Public Transportation
  * Service & Parts
* Bills & Utilities
  * Domain Names
  * Fraud Protection
  * Home Phone
  * Hosting
  * Internet
  * Mobile Phone
  * Television
  * Utilities
* Business Services
  * Advertising
  * Legal
  * Office Supplies
  * Printing
  * Shipping
* Education
  * Books & Supplies
  * Student Loan
  * Tuition
* Entertainment
  * Amusement
  * Arts
  * Movies & DVDs
  * Music
  * Newspapers & Magazines
* Fees & Charges
  * ATM Fee
  * Banking Fee
  * Finance Charge
  * Late Fee
  * Service Fee
  * Trade Commissions
* Financial
  * Financial Advisor
  * Life Insurance
* Food & Dining
  * Alcohol & Bars
  * Coffee Shops
  * Fast Food
  * Groceries
  * Restaurants
* Gifts & Donations
  * Charity
  * Gift
* Health & Fitness
  * Dentist
  * Doctor
  * Eyecare
  * 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
  * Returned Purchase
* Investments
  * Buy
  * Deposit
  * Dividend & Cap Gains
  * Sell
  * Withdrawal
* Kids
  * Allowance
  * 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
  * Hobbies
  * Sporting Goods
* Taxes
  * Federal Tax
  * Local Tax
  * Property Tax
  * Sales Tax
  * State Tax
* Transfer
  * Credit Card Payment
  * Transfer for Cash Spending
  * Mortgage Payment
* Travel
  * Air Travel
  * Hotel
  * Rental Car & Taxi
  * Vacation
* Uncategorized
  * Cash
  * Check

Merchant category codes

Merchant category code MX category Merchant category
742 Veterinary Veterinary Services
763 Food & Dining Agricultural Cooperative
780 Lawn & Garden Landscaping Services
1520 Home Improvement General Contractors
1711 Home Improvement Heating, Plumbing, A/C
1731 Home Improvement Electrical Contractors
1740 Home Improvement Masonry, Stonework, and Plaster
1750 Home Improvement Carpentry Contractors
1761 Home Improvement Roofing/Siding, Sheet Metal
1771 Home Improvement Concrete Work Contractors
1799 Home Improvement Special Trade Contractors
2741 Printing Miscellaneous Publishing and Printing
2791 Printing Typesetting, Plate Making, and Related Services
2842 Home Services Specialty Cleaning
3000 Air Travel Default Category For 3000-3301
3351 Rental Car & Taxi Default Category For 3351-3441
3501 Hotel Default Category For 3501-3836
4011 Travel Railroads
4111 Travel Commuter Transport, Ferries
4112 Travel Passenger Railways
4119 Doctor Ambulance Services
4121 Rental Car & Taxi Taxicabs/Limousines
4131 Travel Bus Lines
4214 Shipping Motor Freight Carriers and Trucking
4215 Shipping Courier Services
4225 Shipping Public Warehousing and Storage - Farm Products, Refrigerated Goods
4411 Travel Cruise Lines
4457 Travel Boat Rentals and Leases
4468 Travel Marinas, Service and Supplies
4511 Air Travel Airlines, Air Carriers
4582 Travel Airports, Flying Fields
4722 Travel Travel Agencies, Tour Operators
4723 Travel TUI Travel - Germany
4784 Travel Tolls/Bridge Fees
4789 Travel Transportation Services (Not Elsewhere Classified)
4812 Home Phone Telecommunication Equipment and Telephone Sales
4814 Home Phone Telecommunication Services
4816 Internet Computer Network Services
4821 Bills & Utilities Telegraph Services
4829 Transfer Wires, Money Orders
4899 Utilities Cable, Satellite, and Other Pay Television and Radio
4900 Utilities Utilities
5013 Service & Parts Motor Vehicle Supplies and New Parts
5021 Furnishings Office and Commercial Furniture
5039 Home Improvement Construction Materials (Not Elsewhere Classified)
5044 Business Services Photographic, Photocopy, Microfilm Equipment, and Supplies
5045 Electronics & Software Computers, Peripherals, and Software
5046 Shopping Commercial Equipment (Not Elsewhere Classified)
5047 Health & Fitness Medical, Dental, Ophthalmic, and Hospital Equipment and Supplies
5051 Home Metal Service Centers
5065 Home Electrical Parts and Equipment
5072 Home Hardware, Equipment, and Supplies
5074 Home Plumbing, Heating Equipment, and Supplies
5085 Home Industrial Supplies (Not Elsewhere Classified)
5094 Shopping Precious Stones and Metals, Watches and Jewelry
5099 Shopping Durable Goods (Not Elsewhere Classified)
5111 Office Supplies Stationary, Office Supplies, Printing and Writing Paper
5122 Pharmacy Drugs, Drug Proprietaries, and Druggist Sundries
5131 Clothing Piece Goods, Notions, and Other Dry Goods
5137 Clothing Uniforms, Commercial Clothing
5139 Clothing Commercial Footwear
5169 Home Chemicals and Allied Products (Not Elsewhere Classified)
5172 Gas Petroleum and Petroleum Products
5192 Books Books, Periodicals, and Newspapers
5193 Shopping Florists Supplies, Nursery Stock, and Flowers
5198 Home Supplies Paints, Varnishes, and Supplies
5199 Home Nondurable Goods (Not Elsewhere Classified)
5200 Home Home Supply Warehouse Stores
5211 Home Lumber, Building Materials Stores
5231 Home Glass, Paint, and Wallpaper Stores
5251 Home Hardware Stores
5261 Lawn & Garden Nurseries, Lawn and Garden Supply Stores
5271 Shopping Mobile Home Dealers
5300 Shopping Wholesale Clubs
5309 Shopping Duty Free Stores
5310 Shopping Discount Stores
5311 Shopping Department Stores
5331 Shopping Variety Stores
5399 Shopping Miscellaneous General Merchandise
5411 Groceries Grocery Stores, Supermarkets
5422 Groceries Freezer and Locker Meat Provisioners
5441 Groceries Candy, Nut, and Confectionery Stores
5451 Groceries Dairy Products Stores
5462 Groceries Bakeries
5499 Groceries Miscellaneous Food Stores - Convenience Stores and Specialty Markets
5511 Auto & Transport Car and Truck Dealers (New & Used) Sales, Service, Repairs Parts and Leasing
5521 Auto & Transport Car and Truck Dealers (Used Only) Sales, Service, Repairs Parts and Leasing
5531 Auto & Transport Auto and Home Supply Stores
5532 Auto & Transport Automotive Tire Stores
5533 Auto & Transport Automotive Parts and Accessories Stores
5541 Gas Service Stations
5542 Gas Automated Fuel Dispensers
5551 Auto & Transport Boat Dealers
5561 Auto & Transport Motorcycle Shops, Dealers
5571 Auto & Transport Motorcycle Shops and Dealers
5592 Auto & Transport Motor Homes Dealers
5598 Sporting Goods Snowmobile Dealers
5599 Auto & Transport Miscellaneous Auto Dealers
5611 Clothing Men’s and Boy’s Clothing and Accessories Stores
5621 Clothing Women’s Ready-To-Wear Stores
5631 Clothing Women’s Accessory and Specialty Shops
5641 Clothing Children’s and Infant’s Wear Stores
5651 Clothing Family Clothing Stores
5655 Clothing Sports and Riding Apparel Stores
5661 Clothing Shoe Stores
5681 Clothing Furriers and Fur Shops
5691 Clothing Men’s, Women’s Clothing Stores
5697 Clothing Tailors, Alterations
5698 Hair Wig and Toupee Stores
5699 Clothing Miscellaneous Apparel and Accessory Shops
5712 Furnishings Furniture, Home Furnishings, and Equipment Stores, Except Appliances
5713 Furnishings Floor Covering Stores
5714 Furnishings Drapery, Window Covering, and Upholstery Stores
5718 Furnishings Fireplace, Fireplace Screens, and Accessories Stores
5719 Furnishings Miscellaneous Home Furnishing Specialty Stores
5722 Home Household Appliance Stores
5732 Electronics & Software Electronics Stores
5733 Music Music Stores-Musical Instruments, Pianos, and Sheet Music
5734 Electronics & Software Computer Software Stores
5735 Music Record Stores
5811 Restaurants Caterers
5812 Restaurants Eating Places, Restaurants
5813 Alcohol & Bars Drinking Places
5814 Fast Food Fast Food Restaurants
5815 Entertainment Digital Goods Media - Books, Movies, Music
5816 Entertainment Digital Goods - Games
5817 Shopping Digital Goods - Applications (Excludes Games)
5818 Shopping Digital Goods - Large Digital Goods Merchant
5912 Pharmacy Drug Stores and Pharmacies
5921 Alcohol & Bars Package Stores-Beer, Wine, and Liquor
5931 Clothing Used Merchandise and Secondhand Stores
5932 Shopping Antique Shops
5933 Shopping Pawn Shops
5935 Service & Parts Wrecking and Salvage Yards
5937 Shopping Antique Reproductions
5940 Sporting Goods Bicycle Shops
5941 Sporting Goods Sporting Goods Stores
5942 Books Book Stores
5943 Office Supplies Stationery Stores, Office, and School Supply Stores
5944 Shopping Jewelry Stores, Watches, Clocks, and Silverware Stores
5945 Shopping Hobby, Toy, and Game Shops
5946 Shopping Camera and Photographic Supply Stores
5947 Shopping Gift, Card, Novelty, and Souvenir Shops
5948 Shopping Luggage and Leather Goods Stores
5949 Shopping Sewing, Needlework, Fabric, and Piece Goods Stores
5950 Shopping Glassware, Crystal Stores
5960 Financial Direct Marketing - Insurance Services
5962 Travel Direct Marketing - Travel
5963 Shopping Door-To-Door Sales
5964 Shopping Direct Marketing - Catalog Merchant
5965 Shopping Direct Marketing - Combination Catalog and Retail Merchant
5966 Shopping Direct Marketing - Outbound Tele
5967 Shopping Direct Marketing - Inbound Tele
5968 Shopping Direct Marketing - Subscription
5969 Shopping Direct Marketing - Other
5970 Shopping Artist’s Supply and Craft Shops
5971 Arts Art Dealers and Galleries
5972 Shopping Stamp and Coin Stores
5973 Shopping Religious Goods Stores
5975 Health & Fitness Hearing Aids Sales and Supplies
5976 Health & Fitness Orthopedic Goods - Prosthetic Devices
5977 Personal Care Cosmetic Stores
5978 Office Supplies Typewriter Stores
5983 Gas Fuel Dealers (Non Automotive)
5992 Shopping Florists
5993 Shopping Cigar Stores and Stands
5994 Books News Dealers and Newsstands
5995 Pet Food & Supplies Pet Shops, Pet Food, and Supplies
5996 Home Swimming Pools Sales
5997 Personal Care Electric Razor Stores
5998 Shopping Tent and Awning Shops
5999 Shopping Miscellaneous Specialty Retail
6010 Cash Manual Cash Disburse
6011 Cash Automated Cash Disburse
6012 Financial Financial Institutions
6050 Uncategorized Quasi Cash - Member Financial Institution
6051 Transfer Non-FI, Money Orders
6211 Investments Security Brokers/Dealers
6300 Financial Insurance Underwriting, Premiums
6399 Financial Insurance - Default
6513 Mortgage & Rent Real Estate Agents and Managers - Rentals
6536 Transfer MoneySend Intracountry
6540 Uncategorized Non-Financial Institutions - Stored Value Card Purchase/Load
7011 Hotel Hotels, Motels, and Resorts
7012 Vacation Timeshares
7032 Vacation Sporting/Recreation Camps
7033 Vacation Trailer Parks, Campgrounds
7210 Laundry Laundry, Cleaning Services
7211 Laundry Laundries
7216 Laundry Dry Cleaners
7217 Home Services Carpet/Upholstery Cleaning
7221 Shopping Photographic Studios
7230 Hair Barber and Beauty Shops
7251 Clothing Shoe Repair/Hat Cleaning
7261 Uncategorized Funeral Services, Crematories
7273 Entertainment Dating/Escort Services
7276 Financial Tax Preparation Services
7277 Doctor Counseling Services
7278 Shopping Buying/Shopping Services
7296 Clothing Clothing Rental
7297 Spa & Massage Massage Parlors
7298 Spa & Massage Health and Beauty Spas
7299 Business Services Miscellaneous General Services
7311 Advertising Advertising Services
7321 Financial Credit Reporting Agencies
7333 Business Services Commercial Photography, Art and Graphics
7338 Printing Quick Copy, Repro, and Blueprint
7339 Business Services Secretarial Support Services
7342 Home Exterminating Services
7349 Home Cleaning and Maintenance
7361 Business Services Employment/Temp Agencies
7372 Business Services Computer Programming
7375 Business Services Information Retrieval Services
7379 Electronics & Software Computer Repair
7392 Business Services Consulting, Public Relations
7393 Business Services Detective Agencies
7394 Business Services Equipment Rental
7395 Business Services Photo Developing
7399 Business Services Miscellaneous Business Services
7511 Gas Truck Stop
7512 Rental Car & Taxi Car Rental Agencies
7513 Rental Car & Taxi Truck/Utility Trailer Rentals
7519 Rental Car & Taxi Recreational Vehicle Rentals
7523 Parking Parking Lots, Garages
7531 Service & Parts Auto Body Repair Shops
7534 Service & Parts Tire Retreading and Repair
7535 Service & Parts Auto Paint Shops
7538 Service & Parts Auto Service Shops
7542 Service & Parts Car Washes
7549 Service & Parts Towing Services
7622 Electronics & Software Electronics Repair Shops
7623 Home A/C, Refrigeration Repair
7629 Home Small Appliance Repair
7631 Shopping Watch/Jewelry Repair
7641 Furnishings Furniture Repair, Refinishing
7692 Service & Parts Welding Repair
7699 Service & Parts Miscellaneous Repair Shops
7829 Movies & DVDs Picture/Video Production
7800 Entertainment Government-Owned Lotteries
7801 Entertainment Government Licensed On-Line Casinos (On-Line Gambling)
7802 Entertainment Government-Licensed Horse/Dog Racing
7832 Movies & DVDs Motion Picture Theaters
7841 Movies & DVDs Video Tape Rental Stores
7911 Entertainment Dance Hall, Studios, Schools
7922 Entertainment Theatrical Ticket Agencies
7929 Entertainment Bands, Orchestras
7932 Entertainment Billiard/Pool Establishments
7933 Entertainment Bowling Alleys
7941 Entertainment Sports Clubs/Fields
7991 Entertainment Tourist Attractions and Exhibits
7992 Entertainment Golf Courses - Public
7993 Entertainment Video Amusement Game Supplies
7994 Entertainment Video Game Arcades
7995 Entertainment Betting/Casino Gambling
7996 Entertainment Amusement Parks/Carnivals
7997 Entertainment Country Clubs
7998 Entertainment Aquariums
7999 Entertainment Miscellaneous Recreation Services
8011 Doctor Doctors
8021 Dentist Dentists, Orthodontists
8031 Doctor Osteopaths
8041 Doctor Chiropractors
8042 Eyecare Optometrists, Ophthalmologist
8043 Eyecare Opticians, Eyeglasses
8044 Eyecare Opticians, Eyeglasses
8049 Doctor Chiropodists, Podiatrists
8050 Health & Fitness Nursing/Personal Care
8062 Doctor Hospitals
8071 Doctor Medical and Dental Labs
8099 Doctor Medical Services
8111 Legal Legal Services, Attorneys
8211 Education Elementary, Secondary Schools
8220 Education Colleges, Universities
8241 Education Correspondence Schools
8244 Education Business/Secretarial Schools
8249 Education Vocational/Trade Schools
8299 Education Educational Services
8351 Babysitter & Daycare Child Care Services
8398 Gifts & Donations Charitable and Social Service Organizations - Fundraising
8641 Gifts & Donations Civic, Social, Fraternal Associations
8651 Gifts & Donations Political Organizations
8661 Gifts & Donations Religious Organizations
8675 Gifts & Donations Automobile Associations
8699 Gifts & Donations Membership Organizations
8734 Health & Fitness Testing Laboratories
8911 Business Services Architectural/Surveying Services
8931 Business Services Accounting/Bookkeeping Services
8999 Business Services Professional Services
9211 Legal Court Costs, Including Alimony and Child Support - Courts of Law
9222 Legal Fines - Government Administrative Entities
9223 Legal Bail and Bond Payments
9311 Taxes Tax Payments - Government Agencies
9399 Uncategorized Government Services (Not Elsewhere Classified)
9402 Shipping Postal Services - Government Only
9405 Taxes U.S. Federal Government Agencies or Departments
9950 Business Services Intra-Company Purchases

List transactions by account

This endpoint returns a list of the last 90 days of transactions associated with the specified account.

Query string parameters

Field name Required Data type Description
from_date No String Return transactions occurring within a date range starting on this day. If not set, this defaults to 90 days prior to the day of the request. Must be in ISO 8601 format without a time component.
to_date No String Return transactions occurring in a date range ending on this day. If not set, this defaults to 5 days forward from the day of the request so as to capture pending transactions. Must be in ISO 8601 format without a time component.

Endpoint:

GET /users/{user_guid}/accounts/{account_guid}/transactions

1
2
3

curl -i 'https://int-api.mx.com/users/USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0/accounts/ACT-09c0ee66-51a8-4edf-b977-99534a471134/transactions' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

{
  "transactions": [
    {
      "account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
      "account_id": "account-1040434698",
      "amount": 7.94,
      "category": "Paycheck",
      "check_number_string": null,
      "created_at": "2020-03-02T19:11:11Z",
      "currency_code": "USD",
      "date": "2020-03-02",
      "description": "Paycheck",
      "guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
      "id": "transaction-1040434568",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": false,
      "is_fee": false,
      "is_income": true,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
      "member_is_managed_by_user": true,
      "memo": null,
      "merchant_category_code": null,
      "merchant_guid": null,
      "merchant_location_guid": null,
      "original_description": "Payroll",
      "posted_at": "2020-03-03T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Income",
      "transacted_at": "2020-03-02T12:00:00Z",
      "type": "CREDIT",
      "updated_at": "2020-03-02T19:11:14Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
      "user_id": "user-1040435626"
    },
    {
      "account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
      "account_id": "account-1040434698",
      "amount": 64.77,
      "category": "Mobile Phone",
      "check_number_string": null,
      "created_at": "2020-03-02T19:11:11Z",
      "currency_code": "USD",
      "date": "2020-03-02",
      "description": "Verizon Wirelss",
      "guid": "TRN-3f206b3c-0c6a-4c37-bbe9-c8d60dd953c7",
      "id": "transaction-123057654",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
      "member_is_managed_by_user": true,
      "memo": null,
      "merchant_category_code": null,
      "merchant_guid": "MCH-a5252ab5-56bc-a0ea-7d89-e598a4d5ec0e",
      "merchant_location_guid": null,
      "original_description": "Verizon Wireless",
      "posted_at": "2020-03-03T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Bills & Utilities",
      "transacted_at": "2020-03-02T12:00:00Z",
      "type": "DEBIT",
      "updated_at": "2020-03-02T19:11:14Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
      "user_id": "user-1040435626"
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 20,
    "total_pages": 1
  }
}

List transactions by member

Requests to this endpoint return a list of transactions associated with the specified member, across all accounts associated with that member.

Query string parameters

Field name Required Data type Description
from_date No String Return transactions occurring within a date range starting on this day. If not set, this defaults to 90 days prior to the day of the request. Must be in ISO 8601 format without a time component.
to_date No String Return transactions occurring in a date range ending on this day. If not set, this defaults to 5 days forward from the day of the request so as to capture pending transactions. Must be in ISO 8601 format without a time component.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/transactions

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/transactions' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

{
  "transactions": [
    {
      "account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
      "account_id": "account-1040434698",
      "amount": 7.94,
      "category": "Paycheck",
      "check_number_string": null,
      "created_at": "2020-03-02T19:11:11Z",
      "currency_code": "USD",
      "date": "2020-03-02",
      "description": "Paycheck",
      "guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
      "id": "transaction-1040434568",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": false,
      "is_fee": false,
      "is_income": true,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
      "member_is_managed_by_user": true,
      "memo": null,
      "merchant_category_code": null,
      "merchant_guid": null,
      "merchant_location_guid": null,
      "original_description": "Payroll",
      "posted_at": "2020-03-03T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Income",
      "transacted_at": "2020-03-02T12:00:00Z",
      "type": "CREDIT",
      "updated_at": "2020-03-02T19:11:14Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
      "user_id": "user-1040435626"
    },
    {
      "account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
      "account_id": "account-1040434698",
      "amount": 64.77,
      "category": "Mobile Phone",
      "check_number_string": null,
      "created_at": "2020-03-02T19:11:11Z",
      "currency_code": "USD",
      "date": "2020-03-02",
      "description": "Verizon Wirelss",
      "guid": "TRN-3f206b3c-0c6a-4c37-bbe9-c8d60dd953c7",
      "id": "transaction-123057654",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
      "member_is_managed_by_user": true,
      "memo": null,
      "merchant_category_code": null,
      "merchant_guid": "MCH-a5252ab5-56bc-a0ea-7d89-e598a4d5ec0e",
      "merchant_location_guid": null,
      "original_description": "Verizon Wireless",
      "posted_at": "2020-03-03T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Bills & Utilities",
      "transacted_at": "2020-03-02T12:00:00Z",
      "type": "DEBIT",
      "updated_at": "2020-03-02T19:11:14Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
      "user_id": "user-1040435626"
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 20,
    "total_pages": 1
  }
}

List transactions by user

Requests to this endpoint return a list of transactions associated with the specified user, across all members and accounts associated with that user.

Query string parameters

Field name Required Data type Description
from_date No String Return transactions occurring within a date range starting on this day. If not set, this defaults to 90 days prior to the day of the request. Must be in ISO 8601 format without a time component.
to_date No String Return transactions occurring in a date range ending on this day. If not set, this defaults to 5 days forward from the day of the request so as to capture pending transactions. Must be in ISO 8601 format without a time component.

Endpoint:

GET /users/{user_guid}/transactions

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transactions' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

{
  "transactions": [
    {
      "account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
      "account_id": "account-1040434698",
      "amount": 7.94,
      "category": "Paycheck",
      "check_number_string": null,
      "created_at": "2020-03-02T19:11:11Z",
      "currency_code": "USD",
      "date": "2020-03-02",
      "description": "Paycheck",
      "guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
      "id": "transaction-1040434568",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": false,
      "is_fee": false,
      "is_income": true,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
      "member_is_managed_by_user": true,
      "memo": null,
      "merchant_category_code": null,
      "merchant_guid": null,
      "merchant_location_guid": null,
      "original_description": "Payroll",
      "posted_at": "2020-03-03T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Income",
      "transacted_at": "2020-03-02T12:00:00Z",
      "type": "CREDIT",
      "updated_at": "2020-03-02T19:11:14Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
      "user_id": "user-1040435626"
    },
    {
      "account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
      "account_id": "account-1040434698",
      "amount": 64.77,
      "category": "Mobile Phone",
      "check_number_string": null,
      "created_at": "2020-03-02T19:11:11Z",
      "currency_code": "USD",
      "date": "2020-03-02",
      "description": "Verizon Wirelss",
      "guid": "TRN-3f206b3c-0c6a-4c37-bbe9-c8d60dd953c7",
      "id": "transaction-123057654",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
      "member_is_managed_by_user": true,
      "memo": null,
      "merchant_category_code": null,
      "merchant_guid": "MCH-a5252ab5-56bc-a0ea-7d89-e598a4d5ec0e",
      "merchant_location_guid": null,
      "original_description": "Verizon Wireless",
      "posted_at": "2020-03-03T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Bills & Utilities",
      "transacted_at": "2020-03-02T12:00:00Z",
      "type": "DEBIT",
      "updated_at": "2020-03-02T19:11:14Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
      "user_id": "user-1040435626"
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 20,
    "total_pages": 1
  }
}

Read transaction

Requests to this endpoint will return the attributes of the specified transaction.

Endpoint:

GET /users/{user_guid}/transactions/{transaction_guid}

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transactions/TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

{
  "transaction": {
    "account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
    "account_id": "account-1040434698",
    "amount": 7.94,
    "category": "Paycheck",
    "check_number_string": null,
    "created_at": "2020-03-02T19:11:11Z",
    "currency_code": "USD",
    "date": "2020-03-02",
    "description": "Paycheck",
    "guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
    "id": "transaction-1040434568",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": false,
    "is_fee": false,
    "is_income": true,
    "is_international": null,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": false,
    "is_subscription": false,
    "latitude": null,
    "localized_description": null,
    "localized_memo": null,
    "longitude": null,
    "member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
    "member_is_managed_by_user": true,
    "memo": null,
    "merchant_category_code": null,
    "merchant_guid": null,
    "merchant_location_guid": null,
    "original_description": "Payroll",
    "posted_at": "2020-03-03T12:00:00Z",
    "status": "POSTED",
    "top_level_category": "Income",
    "transacted_at": "2020-03-02T12:00:00Z",
    "type": "CREDIT",
    "updated_at": "2020-03-02T19:11:14Z",
    "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0",
    "user_id": "user-1040435626"
  }
}

Update transaction

Use this endpoint to update the description of a specific transaction according to its unique GUID.

Parameters

Parameter Required?
description Yes

Endpoint:

PUT /users/{user_guid}/transactions/{transaction_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transactions/TRN-bb65493f-326c-4364-b79d-50829bd8277b' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key' \
-H 'Content-Type: application/json' \
-d '{
      "transaction": {
        "description": "new description"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

{
  "transaction": {
    "account_guid": "ACT-5ab76520-e0f8-434f-aedf-4f41b8b3ac6f",
    "account_id": "account-1040434698",
    "amount": 35.71,
    "category": "Shopping",
    "check_number_string": null,
    "created_at": "2020-08-18T20:15:36Z",
    "currency_code": null,
    "date": "2020-08-17",
    "description": "new description",
    "guid": "TRN-bb65493f-326c-4364-b79d-50829bd8277b",
    "id": "transaction-1040434568",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": true,
    "is_fee": false,
    "is_income": false,
    "is_international": null,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": false,
    "is_subscription": false,
    "latitude": null,
    "localized_description": null,
    "localized_memo": null,
    "longitude": null,
    "member_guid": "MBR-0b2121f5-bf4f-4244-a697-cac69160020f",
    "member_is_managed_by_user": true,
    "memo": null,
    "merchant_category_code": 0,
    "merchant_guid": "MCH-f07fcd23-1a18-a1a5-b49b-41d2b1076a69",
    "merchant_location_guid": null,
    "original_description": "Amazon.com*MF1S14RN0",
    "posted_at": "2020-08-17T11:00:00Z",
    "status": "POSTED",
    "top_level_category": "Shopping",
    "transacted_at": "2020-08-17T11:00:00Z",
    "type": "DEBIT",
    "updated_at": "2020-08-24T17:15:21Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "user-1040435626"
  }
}

Users

A user represents a person using the MX Platform API via your application, be it a mobile app, web app, desktop app, etc.

User fields

Field Data Type Description
email String The end user’s email address.
guid String The unique identifier for the user. Defined by MX.
id String A unique, partner-defined, enforced identifier for the user.
is_disabled Boolean This indicates whether the user has been disabled. Defaults to false.
metadata String Additional information you can store about this user. MX recommends using JSON-structured data.

Create user

Use this endpoint to create a new user. The API will respond with the newly-created user object if successful.

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.

Parameters

Field Required?
email No
id No
is_disabled No
metadata No

Endpoint:

POST /users

1
2
3
4
5
6
7
8
9
10
11
12

curl -i -X POST 'https://int-api.mx.com/users' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "user": {
        "id": "partner-2345",
        "is_disabled": false,
        "email": "totally.fake.email@notreal.com",
        "metadata": "Yada yada yada"
      }
    }'

1
2
3
4
5
6
7
8
9

{
  "user": {
    "email": "totally.fake.email@notreal.com",
    "guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "id": "partner-2345",
    "is_disabled": false,
    "metadata": "Yada yada yada"
  }
}

Delete user

Use this endpoint to delete the specified user. The response will have a status of 204 No Content without an object.

Endpoint:

DELETE /users/{user_guid}

1
2
3

curl -i -X DELETE https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53 \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

List users

Requests to this endpoint will return a list of all your users.

Endpoint:

GET /users

1
2
3

curl -i https://int-api.mx.com/users \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

{
  "users": [
    {
      "email": null,
      "guid": "USR-1b7e650e-095e-0667-d673-dea669e59a41",
      "id": "1364598269",
      "is_disabled": false,
      "metadata": null
    },
    {
      "email": "completely.fabricated.user@example.com",
      "guid": "USR-29eab3cf-6a87-fe97-6279-563b63e75a53",
      "id": "098345869540",
      "is_disabled": false,
      "metadata": null
    },
    {
      "email": null,
      "guid": "USR-aeed962a-e6b5-cb30-9640-d3f0f0195a0c",
      "id": "1368496234",
      "is_disabled": false,
      "metadata": null
    },
    {
      "email": null,
      "guid": "USR-8d819d0e-a720-f437-0be3-03a8783086bd",
      "id": "1368544284",
      "is_disabled": false,
      "metadata": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 4,
    "total_pages": 1
  }
}

Read user

Requests to this endpoint will return the details of the specified user.

Endpoint:

GET /users/{user_guid}

1
2
3

curl -i https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53 \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9

{
  "user": {
    "guid": "USR-29eab3cf-6a87-fe97-6279-563b63e75a53",
    "id": "098345869540",
    "email": "completely.fabricated.user@example.com",
    "is_disabled": false,
    "metadata": null
  }
}

Update user

Use this endpoint to update the attributes of the specified user.

Parameters

Field Data type Required?
email String No
id String No
is_disabled Boolean No
metadata String No

Endpoint:

PUT /users/{user_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53 \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "user": {
          "id": "ironman2"
        }
      }'

1
2
3
4
5
6
7
8
9

{
  "user": {
    "email": "completely.fabricated.user@example.com",
    "guid": "USR-29eab3cf-6a87-fe97-6279-563b63e75a53",
    "id": "ironman2",
    "is_disabled": false,
    "metadata": null
  }
}

Default categories

Categories are automatically assigned to a given transaction by the MX system. There are more than a hundred default MX categories and subcategories. The endpoints that follow allow you to list and read those default categories with their attributes.

Category fields

Field Name Data type Description
created_at String The date and time the category was created. This field will always be null when is_default is true.
guid String The unique identifier for the category. Defined by MX.
is_default Boolean This indicates whether the category is an MX-created default category. This will always be false for custom categories.
is_income Boolean This indicates whether the category represents income. This will always be false for custom categories.
metadata String This is additional information a partner can store on the custom category.
name String The name of the custom category.
parent_guid String The unique identifier for the parent category. Defined by MX.
updated_at String The date and time the category was last updated. This field will always be null when is_default is true.

Default transaction categories

* Auto & Transport
  * Auto Insurance
  * Auto Payment
  * Gas
  * Parking
  * Public Transportation
  * Service & Parts
* Bills & Utilities
  * Domain Names
  * Fraud Protection
  * Home Phone
  * Hosting
  * Internet
  * Mobile Phone
  * Television
  * Utilities
* Business Services
  * Advertising
  * Legal
  * Office Supplies
  * Printing
  * Shipping
* Education
  * Books & Supplies
  * Student Loan
  * Tuition
* Entertainment
  * Amusement
  * Arts
  * Movies & DVDs
  * Music
  * Newspapers & Magazines
* Fees & Charges
  * ATM Fee
  * Banking Fee
  * Finance Charge
  * Late Fee
  * Service Fee
  * Trade Commissions
* Financial
  * Financial Advisor
  * Life Insurance
* Food & Dining
  * Alcohol & Bars
  * Coffee Shops
  * Fast Food
  * Groceries
  * Restaurants
* Gifts & Donations
  * Charity
  * Gift
* Health & Fitness
  * Dentist
  * Doctor
  * Eyecare
  * 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
  * Allowance
  * 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 for Cash Spending
  * Mortgage Payment
* Travel
  * Air Travel
  * Hotel
  * Rental Car & Taxi
  * Vacation
* Uncategorized
  * Cash
  * Check

List default categories (excluding custom categories)

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.

Endpoint:

GET /users/{user_guid}/categories/default

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories/default' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

{
  "categories": [
    {
      "created_at": null,
      "guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
      "is_default": true,
      "is_income": false,
      "metadata": null,
      "name": "Auto & Transport",
      "parent_guid": null,
      "updated_at": null
    },
    {
      "created_at": null,
      "guid": "CAT-de7c2dc7-90e6-85a2-6509-5ec10942e887",
      "is_default": true,
      "is_income": false,
      "metadata": null,
      "name": "Auto Insurance",
      "parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
      "updated_at": null
    },
    {
      "created_at": null,
      "guid": "CAT-cb93691a-684d-b326-4c32-f8abaecfde90",
      "is_default": true,
      "is_income": false,
      "metadata": null,
      "name": "Auto Payment",
      "parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
      "updated_at": null
    }
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 8,
    "total_pages": 1
  }
}

Read category

Use this endpoint to read the attributes of either a default category or a custom category.

Endpoint:

GET /users/{user_guid}/categories/{category_guid}

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories/CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12

{
  "category": {
    "created_at": null,
    "guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
    "is_default": true,
    "is_income": false,
    "metadata": null,
    "name": "Auto & Transport",
    "parent_guid": null,
    "updated_at": null
  }
}

Enhance transactions

Use this endpoint to enhance your partner-provided transactional data. Each transaction you provide will be categorized, given a cleansed description, and possibly assigned one or more classifications, merchants, or merchant locations.

Enhanced transactions are not persisted or stored by MX. They are simply returned in their enhanced form. Enhanced transactions are returned with only a subset of the fields stored on persistent transactions.

Enhanced transaction fields

Field Data type Definition
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.
description String A human-readable version of the original_description field described below, e.g., “Sam’s Club,” “Johnny’s Tavern.” This is provided by the MX Platform.
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.
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.

Parameters

Field Name Required?
amount No
description Yes
id Yes
merchant_category_code No
type No

Endpoint:

POST /transactions/enhance

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl -i -X POST 'https://int-api.mx.com/transactions/enhance'
-u 'client_id:api_key'
-H 'Accept: application/vnd.mx.api.v1+json'
-H 'Content-Type: application/json'
-d'{
    "transactions": [
      {
        "amount": 11.22,
        "description": "ubr* pending.uber.com",
        "id": "12",
        "type": "DEBIT"
      }
    ]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "transactions": [
    {
      "amount": 11.22,
      "category": "Rental Car & Taxi",
      "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
      "description": "Uber",
      "id": "12",
      "is_bill_pay": null,
      "is_direct_deposit": null,
      "is_expense": null,
      "is_fee": null,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": null,
      "is_payroll_advance": null,
      "is_subscription": null,
      "merchant_category_code": null,
      "merchant_guid": "MCH-14f25b63-ef47-a38e-b2b6-d02b280b6e4e",
      "merchant_location_guid": null,
      "original_description": "ubr* pending.uber.com",
      "type": "DEBIT"
    }
  ]
}

Merchants

A merchant contains information about the merchant, business, company, or seller associated with a specific transaction. This information includes a name, logo, and website.

Merchant fields

Field Data type Description
created_at String The date and time at which the merchant was created.
guid String The unique identifier for the merchant. Defined by MX.
logo_url String The URL for a 100px X 100px logo for the merchant.
logo_updated_at String The date and time the logo associated with this merchant was last updated.
name String A human-readable name for the merchant for display to the end user.
updated_at String The date and time at which the merchant was last updated.
website_url String The URL for the merchant’s website, e.g. https://www.xfinity.com.

List merchants

This endpoint returns a paginated list of all the merchants in the MX system.

Endpoint:

GET /merchants

1
2
3

curl -i 'https://int-api.mx.com/merchants' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

{
  "merchants": [
    {
      "guid": "MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5",
      "logo_url": "https://content.mx.com/logos/merchants/MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5.png",
      "name": "1-800 Contacts",
      "website_url": "https://www.1800contacts.com",
      "created_at": "2018-09-17T19:13:53Z",
      "logo_updated_at": "2021-08-09T16:19:23Z",
      "updated_at": "2021-08-09T16:19:23Z"
    },
    {
      "guid": "MCH-dfef19bb-1af4-bbaa-db41-434b4b1c8f04",
      "logo_url": "https://content.mx.com/logos/merchants/MCH-dfef19bb-1af4-bbaa-db41-434b4b1c8f04.png",
      "name": "1-800-Flowers.com",
      "website_url": "https://www.1800flowers.com",
      "created_at": "2018-07-16T16:31:35Z",
      "logo_updated_at": "2021-02-19T15:58:10Z",
      "updated_at": "2021-02-19T15:58:10Z"
    },
    {
      "guid": "MCH-9559c6fb-c05f-ee9e-bb33-ce23078df1a0",
      "logo_url": "https://content.mx.com/logos/merchants/MCH-9559c6fb-c05f-ee9e-bb33-ce23078df1a0.png",
      "name": "24 Hour Fitness",
      "website_url": "https://www.24hourfitness.com",
      "created_at": "2018-04-23T20:23:59Z",
      "logo_updated_at": "2021-02-19T16:15:59Z",
      "updated_at": "2021-02-19T16:15:59Z"
    },
•••
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_entries": 11443,
    "total_pages": 1145
  }
}

Read merchant

This endpoint returns the attributes of the specified merchant.

Endpoint:

GET /merchants/{merchant_guid}

1
2
3

curl -i 'https://int-api.mx.com/merchants/MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11

{
  "merchant": {
    "created_at": "2018-09-17T19:13:53Z",
    "guid": "MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5",
    "logo_updated_at": "2021-08-09T16:19:23Z",
    "logo_url": "https://content.mx.com/logos/merchants/MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5.png",
    "name": "1-800 Contacts",
    "updated_at": "2021-08-09T16:19:23Z",
    "website_url": "https://www.1800contacts.com"
  }
}

Merchant locations

Merchant locations detail the physical address, longitude, latitude, contact information, etc. for a specific location of a merchant.

Merchant location fields

Field Data Type Definition
city String The city in which the merchant is located.
country String The country in which the merchant is located.
guid String The unique identifier for the merchant location. Defined by MX.
latitude Decimal The latitude of the merchant location. This number is a signed decimal (e.g., Rio de Janeiro’s latitude is -22.9027800 and Tokyo’s latitude is 35.689488).
longitude Decimal The longitude of the merchant location. This number is a signed decimal (e.g., Rio de Janeiro’s longitude is -43.2075000 and Tokyo’s longitude is 139.691706).
merchant_guid String The unique identifier for the merchant to which this location belongs. Defined by MX.
phone_number String The phone number for the merchant location.
postal_code String The postal code in which the merchant is located.
state String The state in which the merchant is located.
street_address String The street address at which the merchant is located.
updated_at String The date and time the merchant_location was last updated.

Read merchant location

This endpoint returns the specified merchant_location resource.

Endpoint:

GET /merchant_locations/{merchant_location_guid}

1
2
3

curl -i -X GET 'https://int-api.mx.com/merchant_locations/MCL-00024e59-18b5-4d79-b879-2a7896726fea' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "merchant_location": {
    "city": "Greenwood Village",
    "country": "US",
    "guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
    "latitude": 39.5963005,
    "longitude": -104.89158799999998,
    "merchant_guid": "MCH-09466f0a-fb58-9d1a-bae2-2af0afbea621",
    "phone_number": "(303) 689-0728",
    "postal_code": "801121436",
    "state": "CO",
    "street_address": "8547 E Arapahoe Rd, Ste 1",
    "updated_at": "2020-04-13T21:05:09Z"
  }
}

Extend history

Some institutions allow developers to access an extended transaction history with up to 24 months of data associated with a particular member. The process for fetching and then reading this extended transaction history is much like standard aggregation, and it may trigger multi-factor authentication.

Use this endpoint to gather an extended transaction history for a particular member. This longer history can then be accessed though the standard transaction endpoints.

If an extended transaction process is already running, a 202 Accepted status will be returned. If another aggregation-type process is already running — like standard aggregation or verification — a 409 Conflict will be returned.

Endpoint:

POST /users/{user_guid}/members/{member_guid}/extend_history

1
2
3
4

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-0b2121f5-bf4f-4244-a697-cac69160020f/extend_history' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

Identity

Identity allows you to access data such as the name, street address, phone number, and email address for all the accounts associated with a particular member. The process for getting an account owner’s identity is much like standard aggregation.

The identify endpoint may be used to gather this information on certain institutions, and then it can be accessed with another call to the account owners endpoint.

Account owner fields

Field Data Type Description
account_guid String The unique identifier for the account associated with the account owner. Defined by MX.
address String The account owner’s street address.
city String The account owner’s city.
country String The account owner’s country.
email String The account owner’s email address.
guid String The unique identifier for the account owner. Defined by MX.
member_guid String The unique identifier for the member associated with the account owner. Defined by MX.
owner_name String The account owner’s name.
phone String The account owner’s phone number.
postal_code String The the account owner’s postal code.
state String The account owner’s state.
user_guid String The unique identifier for the user associated with the account owner. Defined by MX.

Identify member

The identify endpoint begins an identification process for an already-existing member.

The identification workflow is similar to standard aggregation: Start the identification, check the connection status, answer MFA if necessary, check the connection status again, then read the member’s account numbers.

If an identification is already running, a 202 Accepted status will be returned. If another aggregation-type process is already running — like standard aggregation or extended transaction history — a 409 Conflict will be returned.

Parameters

Field name Definition Required?
include_transactions When set to true, the identification will gather transaction data along with account owner data. Defaults to false. No

Endpoint:

POST /users/{user_guid}/members/{member_guid}/identify

1
2
3
4

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/identify' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

Example request with parameters

1
2
3
4
5
6
7
8
9

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/identify' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json'
  -d '{
      "member": {
        "include_transactions": true
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

List account owners

Use this endpoint to check whether identity data is available for a specific member. It returns the account_owners resource, which contains an array with data about the owners of each account associated with the member.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/account_owners

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/account_owners' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

{
  "account_owners": [
    {
      "guid": "ACO-123",
      "user_guid": "USR-123",
      "member_guid": "MBR-123",
      "account_guid": "ACT-123",
      "owner_name": "Donnie Darko",
      "address": "123 This Way",
      "city": "Middlesex",
      "state": "VA",
      "postal_code": "00000-0000",
      "country": "US",
      "email": "donnie@darko.co",
      "phone": "555-555-5555"
    },
    {
      "guid": "ACO-456",
      "user_guid": "USR-123",
      "member_guid": "MBR-123",
      "account_guid": "ACT-123",
      "owner_name": "Susan Darko",
      "address": "456 That Way",
      "city": "Middlesex",
      "state": "VA",
      "postal_code": "00000-0000",
      "country": "US",
      "email": "susan@darko.co",
      "phone": "555-555-5555"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

Holdings

Holdings represent a stock, bond, or other type of investment.

Holding fields

Field Data type Description
account_guid String The unique identifier for the account associated with the holding. Defined by MX.
cost_basis Decimal The cost basis is the original value of an asset adjusted for stock splits, dividends, and capital distributions.
created_at String Date and time the holding was created, represented in ISO 8601 format, with a timestamp.
currency_code String The three-character ISO 4217 currency code.
cusip String An identification number assigned to stocks and registered bonds.
daily_change Decimal The change from the previous day in the price of the holding.
description String A human-readable description of the holding.
guid String The unique identifier for the holding. Defined by MX.
holding_type String The type of holding, e.g., mutual fund, bond, etc.
id String The unique partner-defined identifier for the holding.
market_value Decimal The market value of the holding.
member_guid String The unique identifier for the member associated with the holding.
metadata String Additional information you can store on this holding.
purchase_price String The purchase price of the holding.
shares Decimal The number of shares for the holding.
symbol String The ticker symbol, i.e. the abbreviation used to uniquely identify publicly traded stocks, bonds, mutual funds, and ETFs.
updated_at String The date and time the holding was last updated, represented in ISO 8601 format with timestamp.
user_guid String The unique identifier for the user associated with the holding.

Holding types and subtypes

Type integer Type string
0 UNKNOWN_TYPE
1 EQUITY
2 EXCHANGE_TRADED_FUND
3 MONEY_MARKET
4 MUTUAL_FUND
5 HEDGE_FUND
6 ANNUITY
7 UNIT_INVESTMENT_TRUST
8 CASH
9 FIXED_INCOME
10 OPTIONS
11 ALTERNATIVE_INVESTMENTS
12 CERTIFICATE_OF_DEPOSIT
13 LOAN
Subtype integer Subtype string Parent type string
0 UNKNOWN_SUBTYPE
1 AMERICAN_DEPOSITARY_RECEIPT EQUITY
2 STABLE_VALUE_FUND MONEY_MARKET
3 SEPARATE_ACCOUNT MUTUAL_FUND
4 SEGREGATED_FUND MUTUAL_FUND
5 LABOUR_SPONSORED_INVESTMENT MUTUAL_FUND
6 COLLECTIVE_INVESTMENT_TRUST MUTUAL_FUND
7 COLLEGE_SAVINGS MUTUAL_FUND
8 INCOME_TRUST MUTUAL_FUND
9 MUNICIPAL_BOND FIXED_INCOME
10 CORPORATE_BOND FIXED_INCOME
11 TREASURY_SECURITY FIXED_INCOME
12 AGENCY_SECURITY FIXED_INCOME
13 MORTGAGE_BACKED_BOND FIXED_INCOME
14 INTERNATIONAL_BOND FIXED_INCOME
15 EMPLOYEE_STOCK_OPTIONS OPTIONS
16 RESTRICTED_STOCK_UNITS OPTIONS
17 RESTRICTED_STOCK OPTIONS
18 STOCK_APPRECIATION_RIGHT OPTIONS
19 LIMITED_PARTNERSHIP_UNITS ALTERNATIVE_INVESTMENTS
20 STRUCTURED_PRODUCT ALTERNATIVE_INVESTMENTS
21 GUARANTEED_INVESTMENT_CERTIFICATE CERTIFICATE_OF_DEPOSIT

List holdings by member

This endpoint returns all holdings associated with the specified member across all accounts.

Query string parameters

Field name Required Data type Description
from_date No String Return transactions occurring within a date range starting on this day. If not set, this defaults to 90 days prior to the day of the request. Must be in ISO 8601 format without a time component.
to_date No String Return transactions occurring in a date range ending on this day. If not set, this defaults to 5 days forward from the day of the request so as to capture pending transactions. Must be in ISO 8601 format without a time component.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/holdings

1
2
3

curl -i 'https://int-api.mx.com/users/USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0/members/MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225/holdings' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

{
  "holdings": [
    {
      "account_guid": "ACT-f3a6ddfb-3768-4713-87a0-4ad04f87c396",
      "cost_basis": null,
      "created_at": "2019-08-02T17:43:22Z",
      "currency_code": "USD",
      "cusip": "70450Y103",
      "daily_change": null,
      "description": "PayPal Holdings Inc.",
      "guid": "HOL-bd3bc50f-5a70-4226-abef-ae9bb4c1cb1a",
      "holding_type": 9,
      "id": "holding-8417f306-7113-485f-b209-3864ae82fdd7",
      "market_value": 57,
      "member_guid": null,
      "metadata": null,
      "purchase_price": 26,
      "shares": 37,
      "symbol": "PYPL",
      "updated_at": "2020-03-02T19:11:02Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0"
    },
    {
      "account_guid": "ACT-f3a6ddfb-3768-4713-87a0-4ad04f87c396",
      "cost_basis": null,
      "created_at": "2019-08-02T17:43:22Z",
      "currency_code": "USD",
      "cusip": "99UBAYWG0",
      "daily_change": null,
      "description": "American Airlines Group Inc.",
      "guid": "HOL-813a8b86-0dfd-4e8b-8852-24e9a5a0c688",
      "holding_type": 10,
      "id": "holding-a3fccf60-9a89-4a90-aaaf-0462a4e40bef",
      "market_value": 4,
      "member_guid": null,
      "metadata": null,
      "purchase_price": 60,
      "shares": 31,
      "symbol": "AAL",
      "updated_at": "2020-03-02T19:11:02Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0"
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 10,
    "total_pages": 1
  }
}

List holdings by user

This endpoint returns all holdings associated with the specified user across all accounts and members.

Query string parameters

Field name Required Data type Description
from_date No String Return transactions occurring within a date range starting on this day. If not set, this defaults to 90 days prior to the day of the request. Must be in ISO 8601 format without a time component.
to_date No String Return transactions occurring in a date range ending on this day. If not set, this defaults to 5 days forward from the day of the request so as to capture pending transactions. Must be in ISO 8601 format without a time component.

Endpoint:

GET /users/{user_guid}/holdings

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/holdings' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

{
  "holdings": [
    {
      "account_guid": "ACT-f3a6ddfb-3768-4713-87a0-4ad04f87c396",
      "cost_basis": null,
      "created_at": "2019-08-02T17:43:22Z",
      "currency_code": "USD",
      "cusip": "70450Y103",
      "daily_change": null,
      "description": "PayPal Holdings Inc.",
      "guid": "HOL-bd3bc50f-5a70-4226-abef-ae9bb4c1cb1a",
      "holding_type": 9,
      "id": "holding-8417f306-7113-485f-b209-3864ae82fdd7",
      "market_value": 57,
      "member_guid": null,
      "metadata": null,
      "purchase_price": 26,
      "shares": 37,
      "symbol": "PYPL",
      "updated_at": "2020-03-02T19:11:02Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0"
    },
    {
      "account_guid": "ACT-f3a6ddfb-3768-4713-87a0-4ad04f87c396",
      "cost_basis": null,
      "created_at": "2019-08-02T17:43:22Z",
      "currency_code": "USD",
      "cusip": "99UBAYWG0",
      "daily_change": null,
      "description": "American Airlines Group Inc.",
      "guid": "HOL-813a8b86-0dfd-4e8b-8852-24e9a5a0c688",
      "holding_type": 10,
      "id": "holding-a3fccf60-9a89-4a90-aaaf-0462a4e40bef",
      "market_value": 4,
      "member_guid": null,
      "metadata": null,
      "purchase_price": 60,
      "shares": 31,
      "symbol": "AAL",
      "updated_at": "2020-03-02T19:11:02Z",
      "user_guid": "USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0"
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 10,
    "total_pages": 1
  }
}

Read holding

This endpoint returns all holdings associated with the specified account.

Endpoint:

GET /users/{user_guid}/holdings/{holding_guid}

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/holdings/HOL-57ffa88f-f630-4232-991e-4f82a783f24e' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "holding": {
    "account_guid": "ACT-34088d82-dbca-4d99-ae7e-e3176df9c306",
    "cost_basis": null,
    "created_at": "2019-08-08T16:15:30Z",
    "currency_code": "USD",
    "cusip": "278642103",
    "daily_change": null,
    "description": "eBay Inc.",
    "guid": "HOL-57ffa88f-f630-4232-991e-4f82a783f24e",
    "holding_type": 5,
    "id": "holding-f0093b53-3af9-4784-b129-b4ff185614fa",
    "market_value": 5,
    "member_guid": null,
    "metadata": null,
    "purchase_price": 24,
    "shares": 12,
    "symbol": "EBAY",
    "updated_at": "2019-08-08T16:15:30Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Managed institutions

A partner-managed institution is a representation of your real-world financial institution on the MX platform.

List managed insitutions

This endpoint returns a list of institutions which can be used to create partner-managed members.

Endpoint:

GET /managed_institutions

1
2
3

curl -i 'https://int-api.mx.com/managed_institutions' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "institutions": [
    {
      "code": "partnerinstitutioncode",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "Partner Institution",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": false,
      "supports_account_statement": false,
      "supports_account_verification": false,
      "supports_oauth": false,
      "supports_transaction_history": false,
      "url": "https://PrtnerInstitutionWebsite.com"
    },
    {
      "code": "mxbank",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-1572a04c-912b-59bf-5841-332c7dfafaef_100x100.png",
      "name": "MX Bank",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-1572a04c-912b-59bf-5841-332c7dfafaef_50x50.png",
      "supports_account_identification": true,
      "supports_account_statement": false,
      "supports_account_verification": true,
      "supports_oauth": false,
      "supports_transaction_history": true,
      "url": "https://www.mx.com"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 2,
    "total_pages": 1
  }
}

Managed members

A partner-managed member represents the relationship between a user and your institution; the member’s data is managed by you.

Partner-managed members are not aggregated, and thus do not have credentials.

Managed member fields

Field Data type Definition
aggregated_at String The date and time the account was last aggregated.
connection_status String This indicates the state of a member’s aggregation. See member connection statuses for more information.
guid String The unique identifier for the member. Defined by MX.
id String The partner-defined unique identifier for the member.
institution_code String The unique identifier for the institution associated with the member. Defined by MX.
is_being_aggregated Boolean This indicates whether the member was being aggregated at the time of the request.
is_managed_by_user String 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.
is_oauth Boolean This indicates whether the member uses OAuth to authenticate. Defaults to false.
metadata String Additional information you can store on this member.
name String The name of the member.
successfully_aggregated_at String The date and time the member was last successfully aggregated.
user_guid String The unique identifier for the user associated with the member. Defined by MX.
user_id String the unique, partner-defined identifier for the user associated with this member.

Create a managed member

Use this endpoint to create a new partner-managed member.

Parameters

Field Data type Required?
id String No
institution_code String Yes (This should always be set to your default institution.)
metadata String No
name String No

Endpoint:

POST /users/{user_guid}/managed_members

1
2
3
4
5
6
7
8
9
10
11

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -d '{
        "member": {
            "institution_code": "mxbank",
            "id": "partner-1234",
            "metadata": "this and that"
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "member": {
    "aggregated_at": null,
    "connection_status": "CONNECTED",
    "guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "id": "partner-1234",
    "institution_code": "aef89293-88d9-42e6-82a2-0a2b14fe7667",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "this and that",
    "name": null,
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "partner-2345"
  }
}

Delete a managed member

Use this endpoint to delete the specified partner-managed member. The endpoint will respond with a status of 204 No Content without a resource.

Endpoint:

DELETE /users/{user_guid}/managed_members/{member_guid}

1
2
3

curl -i -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

List managed members

This endpoint returns a list of all the partner-managed members associated with the specified user.

Endpoint:

GET /users/{user_guid}/managed_members

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "members": [
    {
      "aggregated_at": null,
      "connection_status": "CREATED",
      "guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
      "id": "partner-1234",
      "institution_code": "mxbank",
      "is_being_aggregated": false,
      "metadata": "this and that",
      "name": "MX Bank",
      "successfully_aggregated_at": null,
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read a managed member

This endpoint returns the attributes of the specified partner-managed member.

Endpoint:

GET /users/{user_guid}/managed_members/{member_guid}

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "id": "partner-1234",
    "institution_code": "mxbank",
    "is_being_aggregated": false,
    "metadata": "this and that",
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Update a managed member

Use this endpoint to update the attributes of the specified partner_managed member.

Parameters

Field Data type Required?
id String No
metadata String No
name String No

Endpoint:

PUT /users/{user_guid}/managed_members/{member_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -d '{
        "member": {
          "metadata": "New metadata"
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "id": "partner-1234",
    "institution_code": "mxbank",
    "is_being_aggregated": false,
    "metadata": "New metadata",
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Managed accounts

A partner-managed account is an account which belongs to a partner-managed member. Data on these accounts is not gathered through aggregation. Partners must provide and update all data on managed accounts.

Managed account fields

Field Data type Description
account_number String The account number associated with the account. This will typically be a masked or partial account number.
apr Decimal The annual percentage rate associated with the account.
apy Decimal The annual percentage yield associated with the account.
available_balance Decimal The balance that is available for use in asset accounts like checking and savings. PENDING transactions are typically taken into account with the available balance, but this may not always be the case.

available_balance will usually be a positive value for all account types, determined in the same way as the balance field.
available_credit Decimal The amount of credit available for use in liability accounts like credit cards and lines of credit. PENDING transactions are typically taken into account with available credit, but this may not always be the case.

available_credit will usually be a positive value for all account types, determined in the same way as the balance field.
balance Decimal The current balance of the account. PENDING transactions are typically not taken into account with the current balance, but this may not always be the case. This is the value used for the account balance displayed in MX UIs.

The balance will usually be a positive value for all account types. Asset-type accounts (CHECKING, SAVINGS, INVESTMENT) may have a negative balance if they are in overdraft. Debt-type accounts (CREDIT_CARD, LOAN, LINE_OF_CREDIT, MORTGAGE) may have a negative balance if they are overpaid.
cash_balance Decimal The cash balance of the account.
cash_surrender_value Decimal The sum of money paid to the policyholder or annuity holder in the event the policy is voluntarily terminated before it matures, or the insured event occurs.
created_at String The date and time at which the account was created on the MX Platform.
credit_limit Decimal The credit limit associated with the account.
currency_code String The three-character ISO 4217 currency code.
day_payment_is_due Integer The day of the month the payment is due. For example, the 14th is passed as 14.
death_benefit Integer The amount paid to the beneficiary of the account upon death of the account owner.
guid String The unique identifier for the account. Defined by MX.
holdings_value Decimal The value of the holdings associated with the account.
id String The unique partner-defined identifier for the account
imported_at String The date and time at which the account was last successfully aggregated and received data.
institution_code String A unique identifier for the institution associated with this account. Defined by MX.
insured_name String The name of the insured individual.
interest_rate Decimal The interest rate associated with the account.
is_closed Boolean This indicates whether an account has been closed.
is_hidden Boolean This indicates whether the account is hidden. Defaults to false.
last_payment_at String The date and time of the most recent payment on the account.
last_payment Decimal The amount of the most recent payment on the account.
loan_amount Decimal The amount of the loan associated with the account.
matures_on String The date on which the account matures.
member_guid String The unique identifier for the member associated with the account. Defined by MX.
member_id String The unique, partner-defined, identifier for the member associated with this account.
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.
metadata String Additional information a partner can store on the account.
minimum_balance Decimal The minimum balance associated with the account.
minimum_payment Decimal The minimum payment required for an account. This can apply to any debt account.
name String The human-readable name for the account.
nickname String An alternate name for the account.
original_balance Decimal The original balance associated with the account. This will always be positive.
pay_out_amount Decimal The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy.
payment_due_at String The date and time at which the next payment is due on the account.
payoff_balance Decimal The payoff balance for a debt account. This will normally be a positive number.
premium_amount Decimal The insurance policy’s premium amount.
routing_number String The routing number for the account.
started_on String The date on which a debt account was started.
subtype String The account’s subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY.
total_account_value Decimal The total value of the account.
type String The general or parent type of the account.
updated_at String The date and time at which the account was most recently updated.
user_guid String The unique identifier for the user associated with the account. Defined by MX.
user_id String The unique, partner-defined, identifier for the user associated with this account.

Account types and subtypes

Parent types
ANY (not provided by data partner or invalid number provided)
CHECKING
SAVINGS
LOAN
CREDIT_CARD
INVESTMENT
LINE_OF_CREDIT
MORTGAGE
PROPERTY
CASH
INSURANCE
PREPAID
Subtype Parent type
MONEY_MARKET SAVINGS
CERTIFICATE_OF_DEPOSIT SAVINGS
AUTO LOAN
STUDENT LOAN
SMALL_BUSINESS LOAN
PERSONAL LOAN
PERSONAL_WITH_COLLATERAL LOAN
HOME_EQUITY LOAN
PLAN_401_K INVESTMENT
PLAN_403_B INVESTMENT
PLAN_529 INVESTMENT
IRA INVESTMENT
ROLLOVER_IRA INVESTMENT
ROTH_IRA INVESTMENT
TAXABLE INVESTMENT
NON_TAXABLE INVESTMENT
BROKERAGE INVESTMENT
TRUST INVESTMENT
UNIFORM_GIFTS_TO_MINORS_ACT INVESTMENT
PLAN_457 INVESTMENT
PENSION INVESTMENT
EMPLOYEE_STOCK_OWNERSHIP_PLAN INVESTMENT
SIMPLIFIED_EMPLOYEE_PENSION INVESTMENT
SIMPLE_IRA INVESTMENT
BOAT LOAN
POWERSPORTS LOAN
RV LOAN
HELOC LOAN
PLAN_ROTH_401_K INVESTMENT
FIXED_ANNUITY INVESTMENT
VARIABLE_ANNUITY INVESTMENT
VEHICLE_INSURANCE INSURANCE
DISABILITY INSURANCE
HEALTH INSURANCE
LONG_TERM_CARE INSURANCE
PROPERTY_AND_CASUALTY INSURANCE
UNIVERSAL_LIFE INSURANCE
TERM_LIFE INSURANCE
WHOLE_LIFE INSURANCE
ACCIDENTAL_DEATH_AND_DISMEMBERMENT INSURANCE
VARIABLE_UNIVERSAL_LIFE INSURANCE
HSA INVESTMENT
TAX_FREE_SAVINGS_ACCOUNT INVESTMENT
INDIVIDUAL INVESTMENT
REGISTERED_RETIREMENT_INCOME_FUND INVESTMENT
CASH_MANAGEMENT_ACCOUNT INVESTMENT
EMPLOYEE_STOCK_PURCHASE_PLAN INVESTMENT
REGISTERED_EDUCATION_SAVINGS_PLAN INVESTMENT
PROFIT_SHARING_PLAN INVESTMENT
UNIFORM_TRANSFER_TO_MINORS_ACT INVESTMENT
PLAN_401_A INVESTMENT
SARSEP_IRA INVESTMENT
FIXED_ANNUITY_TRADITIONAL_IRA INVESTMENT
VARIABLE_ANNUITY_TRADITIONAL_IRA INVESTMENT
SEPP_IRA INVESTMENT
INHERITED_TRADITIONAL_IRA INVESTMENT
FIXED_ANNUITY_ROTH_IRA INVESTMENT
VARIABLE_ANNUITY_ROTH_IRA INVESTMENT
INHERITED_ROTH_IRA INVESTMENT
COVERDELL INVESTMENT
ADVISORY_ACCOUNT INVESTMENT
BROKERAGE_MARGIN INVESTMENT
CHARITABLE_GIFT_ACCOUNT INVESTMENT
CHURCH_ACCOUNT INVESTMENT
CONSERVATORSHIP INVESTMENT
CUSTODIAL INVESTMENT
DEFINED_BENEFIT_PLAN INVESTMENT
DEFINED_CONTRIBUTION_PLAN INVESTMENT
EDUCATIONAL INVESTMENT
ESTATE INVESTMENT
EXECUTOR INVESTMENT
GROUP_RETIREMENT_SAVINGS_PLAN INVESTMENT
GUARANTEED_INVESTMENT_CERTIFICATE INVESTMENT
HRA INVESTMENT
INDEXED_ANNUITY INVESTMENT
INVESTMENT_CLUB INVESTMENT
IRREVOCABLE_TRUST INVESTMENT
JOINT_TENANTS_BY_ENTIRITY INVESTMENT
JOINT_TENANTS_COMMUNITY_PROPERTY INVESTMENT
JOINT_TENANTS_IN_COMMON INVESTMENT
JOINT_TENANTS_WITH_RIGHTS_OF_SURVIVORSHIP INVESTMENT
KEOUGH_PLAN INVESTMENT
LIFE_INCOME_FUND INVESTMENT
LIVING_TRUST INVESTMENT
LOCKED_IN_RETIREMENT_ACCOUNT INVESTMENT
LOCKED_IN_RETIREMENT_INVESTMENT_FUND INVESTMENT
LOCKED_IN_RETIREMENT_SAVINGS_ACCOUNT INVESTMENT
MONEY_PURCHASE_PLAN INVESTMENT
PARTNERSHIP INVESTMENT
PLAN_409_A INVESTMENT
PLAN_ROTH_403_B INVESTMENT
REGISTERED_DISABILITY_SAVINGS_PLAN INVESTMENT
REGISTERED_LOCKED_IN_SAVINGS_PLAN INVESTMENT
REGISTERED_PENSION_PLAN INVESTMENT
REGISTERED_RETIREMENT_SAVINGS_PLAN INVESTMENT
REVOCABLE_TRUST INVESTMENT
ROTH_CONVERSION INVESTMENT
SOLE_PROPRIETORSHIP INVESTMENT
SPOUSAL_IRA INVESTMENT
SPOUSAL_ROTH_IRA INVESTMENT
TESTAMENTARY_TRUST INVESTMENT
THRIFT_SAVINGS_PLAN INVESTMENT
INHERITED_ANNUITY INVESTMENT
CORPORATE_ACCOUNT INVESTMENT
LIMITED_LIABILITY_ACCOUNT INVESTMENT

Create a managed account

Use this endpoint to create a partner-managed account.

Parameters

Parameters Required?
account_number No
apr No
apy No
available_balance No
available_credit No
balance Yes
cash_surrender_value No
credit_limit No
currency_code No
day_payment_is_due No
death_benefit No
id No
interest_rate No
is_closed No
is_hidden No
last_payment_at No
last_payment No
loan_amount No
matures_on No
metadata No
minimum_balance No
minimum_payment No
name Yes
nickname No
original_balance No
payment_due_at No
payoff_balance No
routing_number No
started_on No
subtype No
type Yes

Endpoint:

POST /users/{user_guid}/managed_members/{member_guid}/accounts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e/accounts' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d'{
      "account": {
        "account_number": "12345",
        "balance": "10000",
        "id": "partner-account-7890",
        "is_closed": false,
        "metadata": "some metadata",
        "name": "Swiss Bank Acct",
        "nickname": "Swiss Account",
        "started_on": "1980-03-28",
        "subtype": "MONEY_MARKET",
        "type": "SAVINGS"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
  "account": {
    "account_number": "12345",
    "apr": null,
    "apy": null,
    "available_balance": 10000.00,
    "available_credit": null,
    "balance": 10000.00,
    "cash_balance": null,
    "cash_surrender_value": null,
    "created_at": "2021-08-31T18:17:44Z",
    "credit_limit": null,
    "currency_code": null,
    "day_payment_is_due": null,
    "death_benefit": null,
    "guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
    "holdings_value": null,
    "id": "partner-account-7890",
    "institution_code": "mxbank",
    "interest_rate": null,
    "insured_name": null,
    "is_closed": false,
    "is_hidden": false,
    "last_payment": null,
    "last_payment_at": null,
    "loan_amount": null,
    "matures_on": null,
    "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "metadata": "some metadata",
    "minimum_balance": null,
    "minimum_payment": null,
    "name": "Swiss Bank Acct",
    "nickname": null,
    "original_balance": null,
    "pay_out_amount": null,
    "payment_due_at": null,
    "payoff_balance": null,
    "premium_amount": null,
    "routing_number": null,
    "started_on": "1980-03-28",
    "subtype": "MONEY_MARKEY",
    "total_account_value": null,
    "type": "SAVINGS",
    "updated_at": "2021-08-31T18:17:44Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Delete a managed account

Use this endpoint to delete a partner-managed account according to its unique GUID. If successful, the API will respond with a status of 204 No Content.

Endpoint:

DELETE /uses/{user_guid}/managed_members/{member_guid}/accounts/{account_guid}

1
2
3

curl -i -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-1b349ca0-d9be-480d-80fd-fce9325c9360/accounts/ACT-1e194555-a690-44ec-b363-282165cf4dab' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

List managed accounts

Use this endpoint to retrieve a list of all the partner-managed accounts associated with the given partner-manage member.

Endpoint:

GET /users/{user_guid}/managed_members/{member_guid}/accounts

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-1b349ca0-d9be-480d-80fd-fce9325c9360/accounts' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

{
  "accounts": [
    {
      "account_number": "12345",
      "apr": null,
      "apy": null,
      "available_balance": null,
      "available_credit": 10000,
      "balance": 10000,
      "cash_balance": null,
      "cash_surrender_value": null,
      "created_at": "2020-08-31T18:17:44Z",
      "credit_limit": null,
      "currency_code": null,
      "day_payment_is_due": 15,
      "death_benefit": null,
      "guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
      "holdings_value": null,
      "id": "1",
      "institution_code": "mxbank",
      "interest_rate": null,
      "insured_name": null,
      "is_closed": false,
      "is_hidden": false,
      "last_payment": 1000.01,
      "last_payment_at": "2011-01-15T17:09:32Z",
      "loan_amount": null,
      "matures_on": "2011-03-28",
      "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
      "metadata": "some metadata",
      "minimum_balance": null,
      "minimum_payment": null,
      "name": "Swiss Bank Acct",
      "nickname": null,
      "original_balance": null,
      "pay_out_amount": null,
      "payment_due_at": "2011-01-15T17:09:32Z",
      "payoff_balance": null,
      "premium_amount": null,
      "routing_number": null,
      "started_on": "1980-03-28",
      "subtype": "SMALL_BUSINESS",
      "total_account_value": null,
      "type": "SAVINGS",
      "updated_at": "2020-08-31T18:17:44Z",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read a managed account

Use this endpoint to read the attributes of a partner-managed account according to its unique guid.

Endpoint:

GET /users/{user_guid}/managed_members/{member_guid}/accounts/{account_guid}

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-1b349ca0-d9be-480d-80fd-fce9325c9360/accounts/ACT-1e194555-a690-44ec-b363-282165cf4dab' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
  "account": {
    "account_number": "12345",
    "apr": null,
    "apy": null,
    "available_balance": null,
    "available_credit": 10000,
    "balance": 10000,
    "cash_balance": null,
    "cash_surrender_value": null,
    "created_at": "2020-08-31T18:17:44Z",
    "credit_limit": null,
    "currency_code": null,
    "day_payment_is_due": 15,
    "death_benefit": null,
    "guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
    "holdings_value": null,
    "id": "1",
    "institution_code": "mxbank",
    "interest_rate": null,
    "insured_name": null,
    "is_closed": false,
    "is_hidden": false,
    "last_payment": 1000.01,
    "last_payment_at": "2011-01-15T17:09:32Z",
    "loan_amount": null,
    "matures_on": "2011-03-28",
    "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "metadata": "some metadata",
    "minimum_balance": null,
    "minimum_payment": null,
    "name": "Swiss Bank Acct",
    "nickname": null,
    "original_balance": null,
    "pay_out_amount": null,
    "payment_due_at": "2011-01-15T17:09:32Z",
    "payoff_balance": null,
    "premium_amount": null,
    "routing_number": null,
    "started_on": "1980-03-28",
    "subtype": "SMALL_BUSINESS",
    "total_account_value": null,
    "type": "SAVINGS",
    "updated_at": "2020-08-31T18:17:44Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Update a managed account

Use this endpoint to update the attributes of a partner-managed account according to its unique GUID.

Parameters

Parameters Required?
account_number No
apr No
apy No
available_balance No
available_credit No
balance No
cash_surrender_value No
credit_limit No
currency_code No
day_payment_is_due No
death_benefit No
id No
interest_rate No
is_closed No
is_hidden No
last_payment_at No
last_payment No
loan_amount No
matures_on No
member_guid No
metadata No
minimum_balance No
minimum_payment No
name No
nickname No
original_balance No
payment_due_at No
payoff_balance No
started_on No
subtype No
type No

Endpoint:

PUT /users/{user_guid}/managed_members/{member_guid}/accounts/{account_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e/accounts/ACT-1e194555-a690-44ec-b363-282165cf4dab' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "account": {
        "balance": 10400.00
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
  "account": {
    "account_number": "12345",
    "apr": null,
    "apy": null,
    "available_balance": 10000.00,
    "available_credit": null,
    "balance": 10400.00,
    "cash_balance": null,
    "cash_surrender_value": null,
    "created_at": "2021-08-31T18:17:44Z",
    "credit_limit": null,
    "currency_code": null,
    "day_payment_is_due": null,
    "death_benefit": null,
    "guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
    "holdings_value": null,
    "id": "partner-account-7890",
    "institution_code": "mxbank",
    "interest_rate": null,
    "insured_name": null,
    "is_closed": false,
    "is_hidden": false,
    "last_payment": null,
    "last_payment_at": null,
    "loan_amount": null,
    "matures_on": null,
    "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "metadata": "some metadata",
    "minimum_balance": null,
    "minimum_payment": null,
    "name": "Swiss Bank Acct",
    "nickname": null,
    "original_balance": null,
    "pay_out_amount": null,
    "payment_due_at": null,
    "payoff_balance": null,
    "premium_amount": null,
    "routing_number": null,
    "started_on": "1980-03-28",
    "subtype": "MONEY_MARKEY",
    "total_account_value": null,
    "type": "SAVINGS",
    "updated_at": "2021-09-01T18:20:37Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Managed transactions

A transaction represents 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, etc. Each transaction belongs to only one account.

A partner-managed transaction is one which belongs to a partner-managed member and account. Data on these transactions is not gathered through aggregation. Partners must provide and update all data on managed transactions.

Managed transaction 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-created identifier for the account. This field is only set with partner-managed transactions.
amount Decimal The monetary amount of the transaction.
category String The category of 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 the transaction was created, given in ISO 8601 format without a timestamp.
description String A human-readable version of the original_description field described below, e.g., “Sam’s Club,” “Johnny’s 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_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 indicates whether a transaction is a recurring credit or debit.
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 (e.g. 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 (e.g. Rio de Janeiro’s longitude is -43.2075000 and Tokyo’s longitude is 139.691706).
member_guid String The unique identifier for the member associated with the transaction Defined by MX.
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.
metadata String Additional information you can store on this transaction.
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.
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. This field is only set with partner-managed transactions.

Create a managed transaction

Use this endpoint to create a new partner-managed transaction.

Parameters

Field Data type Required?
amount String Yes
category String No
check_number_string String No
currency_code String No
description String Yes
id String No
is_international String No
latitude String No
localized_description String No
localized_memo String No
longitude String No
memo String No
metadata String No
merchant_category_code String No
merchant_guid String No
merchant_location_guid String No
posted_at String No
status String Yes
transacted_at String Yes
type String Yes

Endpoint:

POST /users/{user_guid}/managed_members/{managed_member_guid}/accounts/{account_guid}/transactions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e/accounts/ACT-09c0ee66-51a8-4edf-b977-99534a471134/transactions' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
            "id": "partner-transaction-3QP5X0",
            "status": "PENDING",
            "type": "CREDIT",
            "amount": 400,
            "description": "Savings Deposit",
            "is_international": false,
            "transacted_at": "2021-09-01T12:00:00Z",
            "category": "INCOME",
            "latitude": 40.429675,
            "longitude": -111.891982
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

{
  "transaction": {
    "account_guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
    "account_id": "1",
    "amount": 8.2,
    "category": "Gas",
    "check_number_string": "9543",
    "created_at": "2020-06-28T12:00:00Z",
    "currency_code": "USD",
    "date": "2020-03-02",
    "description": "Costcoo Gas",
    "guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
    "id": "T-3QP5X0",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": false,
    "is_fee": false,
    "is_income": true,
    "is_international": false,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": false,
    "is_subscription": false,
    "latitude": "40.429675",
    "localized_description": null,
    "localized_memo": null,
    "longitude": "-111.891982",
    "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "memo": "POS Purchase",
    "merchant_category_code": null,
    "merchant_guid": "MCH-bcd4eed1-f341-b7bb-4cbd-e2a854205306",
    "merchant_location_guid": null,
    "metadata": null,
    "original_description": "COSTCO GAS STATION #22299",
    "posted_at": null,
    "status": null,
    "top_level_category": "Car & Auto",
    "transacted_at": "2020-06-28T12:00:00Z",
    "type": "DEBIT",
    "updated_at": "2020-06-28T12:00:00Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "U-39XBF7"
  }
}

Delete a managed transaction

Use this endpoint to delete the specified partner-managed transaction. The endpoint will respond with a status of 204 No Content without a resource.

Endpoint:

DELETE /users/{user_guid}/managed_members/{managed_member_guid}/accounts/{account_guid}/transactions/{transaction_guid}

1
2
3

curl -L -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e/transactions/TRN-cd2987fe-9afb-e912-a5e3-2eaabb866e43' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

List managed transactions

This endpoint returns a list of all the partner-managed transactions associated with the specified account, scoped through a user and a member.

Endpoint:

GET /users/{user_guid}/managed_members/{managed_member_guid}/accounts/{account_guid}/transactions

1
2
3

curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e/transactions' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

{
  "transactions": [
    {
      "transaction": {
        "account_guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
        "account_id": "1",
        "amount": 8.2,
        "category": "Gas",
        "check_number_string": "9543",
        "created_at": "2020-06-28T12:00:00Z",
        "currency_code": "USD",
        "date": "2020-03-02",
        "description": "Costcoo Gas",
        "guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
        "id": "T-3QP5X0",
        "is_bill_pay": false,
        "is_direct_deposit": false,
        "is_expense": false,
        "is_fee": false,
        "is_income": true,
        "is_international": false,
        "is_overdraft_fee": false,
        "is_payroll_advance": false,
        "is_recurring": false,
        "is_subscription": false,
        "latitude": "40.429675",
        "localized_description": null,
        "localized_memo": null,
        "longitude": "-111.891982",
        "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
        "memo": "POS Purchase",
        "merchant_category_code": null,
        "merchant_guid": "MCH-bcd4eed1-f341-b7bb-4cbd-e2a854205306",
        "merchant_location_guid": null,
        "metadata": null,
        "original_description": "COSTCO GAS STATION #22299",
        "posted_at": null,
        "status": null,
        "top_level_category": "Car & Auto",
        "transacted_at": "2020-06-28T12:00:00Z",
        "type": "DEBIT",
        "updated_at": "2020-06-28T12:00:00Z",
        "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
        "user_id": "U-39XBF7"
    },
    {
        "account_guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
        "account_id": "1",
        "amount": 31.93,
        "category": "Shopping",
        "check_number_string": null,
        "created_at": "2021-06-15T18:37:13Z",
        "currency_code": "USD",
        "date": "2021-06-15",
        "description": "Target",
        "guid": "TRN-2268153b-e423-432b-9a51-e2f886d2f1bd",
        "id": "T-4LY6T1",
        "is_bill_pay": false,
        "is_direct_deposit": false,
        "is_expense": false,
        "is_fee": false,
        "is_income": true,
        "is_international": false,
        "is_overdraft_fee": false,
        "is_payroll_advance": false,
        "is_recurring": false,
        "is_subscription": false,
        "latitude": null,
        "localized_description": null,
        "localized_memo": null,
        "longitude": null,
        "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
        "memo": "POS Purchase",
        "merchant_category_code": null,
        "merchant_guid": null,
        "merchant_location_guid": null,
        "metadata": null,
        "original_description": "TARGET 00009969",
        "posted_at": "2020-06-16T12:00:00Z",
        "status": "POSTED",
        "top_level_category": "Shopping",
        "transacted_at": "2021-06-15T12:00:00Z",
        "type": "DEBIT",
        "updated_at": "2020-06-016T19:11:14Z",
        "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
        "user_id": "U-39XBF7"
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

Read a managed transaction

Requests to this endpoint will return the attributes of the specified partner-managed transaction.

Endpoint:

GET /users/{user_guid}/managed_members/{managed_member_guid}/accounts/{account_guid}/transactions/{transaction_guid}

1
2
3

curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e/transactions/TRN-cd2987fe-9afb-e912-a5e3-2eaabb866e43' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

{
  "transaction": {
    "account_guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
    "account_id": "1",
    "amount": 8.2,
    "category": "Gas",
    "check_number_string": "9543",
    "created_at": "2020-06-28T12:00:00Z",
    "currency_code": "USD",
    "date": "2020-03-02",
    "description": "Costcoo Gas",
    "guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
    "id": "T-3QP5X0",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": false,
    "is_fee": false,
    "is_income": true,
    "is_international": false,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": false,
    "is_subscription": false,
    "latitude": "40.429675",
    "localized_description": null,
    "localized_memo": null,
    "longitude": "-111.891982",
    "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "memo": "POS Purchase",
    "merchant_category_code": null,
    "merchant_guid": "MCH-bcd4eed1-f341-b7bb-4cbd-e2a854205306",
    "merchant_location_guid": null,
    "metadata": null,
    "original_description": "COSTCO GAS STATION #22299",
    "posted_at": null,
    "status": null,
    "top_level_category": "Car & Auto",
    "transacted_at": "2020-06-28T12:00:00Z",
    "type": "DEBIT",
    "updated_at": "2020-06-28T12:00:00Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "U-39XBF7"
  }
}

Update a managed transaction

Use this endpoint to update the attributes of the specified partner_managed transaction.

Parameters

Field Data type Required?
amount String No
category String No
check_number_string String No
currency_code String No
description String No
id String No
is_international String No
latitude String No
localized_description String No
localized_memo String No
longitude String No
memo String No
metadata String No
merchant_category_code String No
merchant_guid String No
merchant_location_guid String No
posted_at String No
status String No
transacted_at String No
type String No

Endpoint:

PUT /users/{user_guid}/managed_members/{managed_member_guid}/accounts/{account_guid}/transactions/{transaction_guid}

1
2
3
4
5
6
7
8
9
10
11

curl -L -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/managed_members/MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e/transactions/TRN-cd2987fe-9afb-e912-a5e3-2eaabb866e43' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "memo": "POS Purchase",
          "posted_at": "2021-06-29T12:00:00Z",
          "status": "POSTED"
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

{
  "transaction": {
    "account_guid": "ACT-1e194555-a690-44ec-b363-282165cf4dab",
    "account_id": "1",
    "amount": 8.2,
    "category": "Gas",
    "check_number_string": "9543",
    "created_at": "2020-06-28T12:00:00Z",
    "currency_code": "USD",
    "date": "2020-03-02",
    "description": "Costcoo Gas",
    "guid": "TRN-181ce5d9-d33e-45b9-a9cd-8f8ef9d82d5d",
    "id": "T-3QP5X0",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": false,
    "is_fee": false,
    "is_income": true,
    "is_international": false,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": false,
    "is_subscription": false,
    "latitude": "40.429675",
    "localized_description": null,
    "localized_memo": null,
    "longitude": "-111.891982",
    "member_guid": "MBR-e6239750-24e8-4833-93a8-d4c2ecf2ec7e",
    "memo": "POS Purchase",
    "merchant_category_code": null,
    "merchant_guid": null,
    "merchant_location_guid": null,
    "metadata": "POS Purchase",
    "original_description": "COSTCO GAS STATION #22299",
    "posted_at": "2021-06-29T12:00:00Z",
    "status": "POSTED",
    "top_level_category": "Car & Auto",
    "transacted_at": "2020-06-28T12:00:00Z",
    "type": "DEBIT",
    "updated_at": "2021-06-29T20:01:30Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "U-39XBF7"
  }
}

Custom categories

Custom categories allow partners and end users to create a new category in addition to the default categories provided in the MX Platform API.

All custom categories must be nested under a parent category; in other words, it must be nested under one of the default categories whose parent_guid field is null.

Custom category fields

Field Name Data type Description
created_at String The date and time the category was created. This field will always be null when is_default is true.
guid String The unique identifier for the category. Defined by MX.
is_default Boolean This indicates whether the category is an MX-created default category. This will always be false for custom categories.
is_income Boolean This indicates whether the category represents income. This will always be false for custom categories.
metadata String This is additional information a partner can store on the custom category.
name String The name of the custom category.
parent_guid String The unique identifier for the parent category. Defined by MX.
updated_at String The date and time the category was last updated. This field will always be null when is_default is true.

Default transaction categories

* Auto & Transport
  * Auto Insurance
  * Auto Payment
  * Gas
  * Parking
  * Public Transportation
  * Service & Parts
* Bills & Utilities
  * Domain Names
  * Fraud Protection
  * Home Phone
  * Hosting
  * Internet
  * Mobile Phone
  * Television
  * Utilities
* Business Services
  * Advertising
  * Legal
  * Office Supplies
  * Printing
  * Shipping
* Education
  * Books & Supplies
  * Student Loan
  * Tuition
* Entertainment
  * Amusement
  * Arts
  * Movies & DVDs
  * Music
  * Newspapers & Magazines
* Fees & Charges
  * ATM Fee
  * Banking Fee
  * Finance Charge
  * Late Fee
  * Service Fee
  * Trade Commissions
* Financial
  * Financial Advisor
  * Life Insurance
* Food & Dining
  * Alcohol & Bars
  * Coffee Shops
  * Fast Food
  * Groceries
  * Restaurants
* Gifts & Donations
  * Charity
  * Gift
* Health & Fitness
  * Dentist
  * Doctor
  * Eyecare
  * 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
  * Allowance
  * 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 for Cash Spending
  * Mortgage Payment
* Travel
  * Air Travel
  * Hotel
  * Rental Car & Taxi
  * Vacation
* Uncategorized
  * Cash
  * Check

Create a custom category

Use this endpoint to create a new custom category for a specific user.

Parameters

Parameter Required?
metadata No
name Yes
parent_guid Yes

Endpoint:

POST /user/{user_guid}/categories

1
2
3
4
5
6
7
8
9
10
11

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "category": {
        "metadata": "Super cool extra info.",
        "name": "Online Shopping",
        "parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12

{
  "category": {
    "created_at": "2020-08-26T20:31:41Z",
    "guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
    "is_default": false,
    "is_income": null,
    "metadata": "Super cool extra info.",
    "name": "Online Shopping",
    "parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f",
    "updated_at": "2020-08-26T20:31:41Z"
  }
}

Delete a custom category

Use this endpoint to delete a specific custom category according to its unique GUID. The API will respond with an empty object and a status of 204 No Content.

Endpoint:

DELETE /users/{user_guid}/categories/{category_guid}

1
2
3

curl -i -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories/CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

List all categories (including custom)

Use this endpoint to list all categories associated with a user, including both default and custom categories.

Endpoint:

GET /users/{user_guid}/categories

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

{
  "categories": [
    {
      "created_at": "2020-08-26T19:56:42Z",
      "guid": "CAT-742dcb38-57e9-4c84-a240-48bc6580ea2e",
      "is_default": false,
      "is_income": null,
      "metadata": null,
      "name": "Some other insurance",
      "parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
      "updated_at": "2020-08-26T19:56:42Z"
    },
    {
      "created_at": "2020-08-26T20:31:41Z",
      "guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
      "is_default": false,
      "is_income": null,
      "metadata": null,
      "name": "New scooter insurance",
      "parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
      "updated_at": "2020-08-26T22:29:03Z"
    },
    {
      "created_at": null,
      "guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
      "is_default": true,
      "is_income": false,
      "metadata": null,
      "name": "Auto & Transport",
      "parent_guid": null,
      "updated_at": null
    },
    {
      "created_at": null,
      "guid": "CAT-de7c2dc7-90e6-85a2-6509-5ec10942e887",
      "is_default": true,
      "is_income": false,
      "metadata": null,
      "name": "Auto Insurance",
      "parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
      "updated_at": null
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 27,
    "total_pages": 2
  }
}

Read a custom category

Use this endpoint to read the attributes of either a default category or a custom category.

Endpoint:

GET /users/{user_guid}/categories/{category_guid}

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories/CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12

{
  "category": {
    "created_at": "2020-08-26T20:31:41Z",
    "guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
    "is_default": false,
    "is_income": null,
    "metadata": null,
    "name": "Scooter Insurance",
    "parent_guid": "CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874",
    "updated_at": "2020-08-26T20:31:41Z"
  }
}

Update a custom category

Use this endpoint to update the attributes of a custom category according to its unique GUID.

Parameters

Parameter Required?
metadata No
name No

Endpoint:

PUT /users/{user_guid}/categories/{category_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories/CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "category": {
        "name": "Web shopping"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12

{
  "category": {
    "created_at": "2020-08-26T20:31:41Z",
    "guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
    "is_default": false,
    "is_income": null,
    "metadata": null,
    "name": "Web shopping",
    "parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f",
    "updated_at": "2020-08-26T22:29:03Z"
  }
}

Tags

Tags allow partners and end users to create a custom label for particular transactions.

Tag fields

Field name Data type Description
guid String Unique identifier for the tag. Defined by MX.
name String The name of the tag. Created by the user.
user_guid String Unique identifier for the user. Defined by MX.

Create tag

Use this endpoint to create a new custom tag.

Parameters

Parameter Required?
name Yes

Endpoint:

POST /users/{user_guid}/tags

1
2
3
4
5
6
7
8
9

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "tag": {
        "name": "MY TAG"
      }
    }'

1
2
3
4
5
6
7

{
  "tag": {
    "guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
    "name": "MY TAG",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Delete tag

Use this endpoint to permanently delete a specific tag based on its unique GUID. If successful, the API will respond with status of 204 No Content.

Endpoint:

DELETE /users/{user_guid}/tags/{tag_guid}

1
2
3

curl -i -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags/TAG-aef36e72-6294-4c38-844d-e573e80aed52' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \

List tags

Use this endpoint to list all tags associated with the specified user. Each user includes the Business tag by default.

Endpoint:

GET /users/{user_guid}/tags

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "tags": [
    {
      "guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
      "name": "MY TAG",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List all transactions for a tag

Use this endpoint to get a list of all transactions associated with a particular tag according to the tag’s unique GUID. In other words, a list of all transactions that have been assigned to a particular tag using the create a tagging endpoint.

Endpoint:

GET /users/{user_guid}/tags/{tag_guid}/transactions

1
2
3
4

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags/TAG-40faf068-abb4-405c-8f6a-e883ed541fff/transactions' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v2+json' \
-H 'Content-Type: application/json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

{
  "transactions": [
    {
      "category": "Mobile Phone",
      "created_at": "2021-04-06T21:03:07Z",
      "date": "2021-04-06",
      "posted_at": "2021-04-07T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Bills & Utilities",
      "transacted_at": "2021-04-06T12:00:00Z",
      "type": "DEBIT",
      "updated_at": "2021-04-06T22:35:47Z",
      "account_guid": "ACT-82ac32b4-06e6-48a9-8440-17e49bb3d720",
      "amount": 70.62,
      "check_number_string": null,
      "currency_code": "USD",
      "description": "Verizon",
      "guid": "TRN-a9f17e04-d19a-4d63-943d-e0d8d8eedb49",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": null,
      "is_subscription": null,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
      "memo": null,
      "merchant_category_code": 0,
      "merchant_guid": "MCH-8324c248-85a9-7071-a29b-1a5b36b4697e",
      "original_description": "Verizon Wireless",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    },
    {
      "category": "Financial",
      "created_at": "2021-04-06T21:03:08Z",
      "date": "2021-04-06",
      "posted_at": "2021-04-07T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Financial",
      "transacted_at": "2021-04-06T12:00:00Z",
      "type": "CREDIT",
      "updated_at": "2021-04-06T22:37:02Z",
      "account_guid": "ACT-4d6b39c7-c130-4279-b70b-e5c18d8a6cf2",
      "amount": 31.59,
      "check_number_string": null,
      "currency_code": "USD",
      "description": "Loan Payment",
      "guid": "TRN-9617ba2d-f4cb-491b-90c4-b2fd1369cd03",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": null,
      "is_subscription": null,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
      "memo": null,
      "merchant_category_code": 0,
      "merchant_guid": null,
      "original_description": "Loan Payment",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

Read tag

Use this endpoint to read the attributes of a particular tag according to its unique GUID.

Endpoint:

GET /users/{user_guid}/tags/{tag_guid}

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags/TAG-aef36e72-6294-4c38-844d-e573e80aed52' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7

{
  "tag": {
    "guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
    "name": "MY TAG",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Update tag

Use this endpoint to update the name of a specific tag according to its unique GUID.

Parameters

Parameter Required?
name Yes

Endpoint:

PUT /users/{user_guid}/tags/{tag_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags/TAG-aef36e72-6294-4c38-844d-e573e80aed52' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "tag": {
        "name": "New Tag Name"
      }
    }'

1
2
3
4
5
6
7

{
  "tag": {
    "guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
    "name": "New Tag Name",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Taggings

Taggings represent the association of a tag to a transaction. In other words, with a tagging, a transaction can be assigned a specific tag, either the default business tag, or any other user-created tag.

Tagging fields

Field name Data type Description
guid String The identifier for the tagging. Defined by MX.
member_is_managed_by_user Boolean This indicates whether the member associated with the transaction is managed by the end user. This defaults to true for members created with the MX Platform API.
tag_guid String The unique identifier for the tag associated with the tagging. Defined by MX.
transaction_guid String The unique identifier for the transaction associated with the tagging. Defined by MX.
user_guid String The unique identifier for the user associated with the tagging. Defined by MX.

Create tagging

Use this endpoint to create a new association between a tag and a particular transaction, according to their unique GUIDs.

Parameters

Parameter Required
tag_guid Yes
transaction_guid Yes

Endpoint:

POST /users/{user_guid}/taggings

1
2
3
4
5
6
7
8
9
10

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "tagging": {
        "tag_guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
        "transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4"
      }
    }'

1
2
3
4
5
6
7
8
9

{
  "tagging": {
    "guid": "TGN-007f5486-17e1-45fc-8b87-8f03984430fe",
    "member_is_managed_by_user": true,
    "tag_guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
    "transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Delete tagging

Use this endpoint to delete a tagging according to its unique GUID. If successful, the API will respond with an empty body and a status of 204 NO Content.

Endpoint:

DELETE /users/{user_guid}/taggings/{tagging_guid}

1
2
3

curl -i -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/TGN-007f5486-17e1-45fc-8b87-8f03984430fe' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

List taggings

Use this endpoint to retrieve a paginated list of all the taggings associated with a specific user.

Endpoint:

GET /users/{user_guid}/taggings

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "taggings": [
    {
      "guid": "TGN-007f5486-17e1-45fc-8b87-8f03984430fe",
      "member_is_managed_by_user": true,
      "tag_guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
      "transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read tagging

Use this endpoint to read the attributes of a tagging according to its unique GUID.

Endpoint:

GET /users/{user_guid}/taggings/{tagging_guid}

1
2
3

curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/TGN-007f5486-17e1-45fc-8b87-8f03984430fe' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

1
2
3
4
5
6
7
8
9

{
  "tagging": {
    "guid": "TGN-007f5486-17e1-45fc-8b87-8f03984430fe",
    "member_is_managed_by_user": true,
    "tag_guid": "TAG-40faf068-abb4-405c-8f6a-e883ed541fff",
    "transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Update tagging

Use this endpoint to update a tagging.

Parameters

Parameter Required?
tag_guid Yes

Endpoint:

PUT /users/{user_guid}/taggings/{tagging_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/TGN-007f5486-17e1-45fc-8b87-8f03984430fe' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "tagging": {
        "tag_guid": "TAG-8ff0ec57-4628-4c7d-86ed-4e0cd78e2971"
      }
    }'

1
2
3
4
5
6
7
8
9

{
  "tagging": {
    "guid": "TGN-007f5486-17e1-45fc-8b87-8f03984430fe",
    "member_is_managed_by_user": true,
    "tag_guid": "TAG-40faf068-abb4-405c-8f6a-e883ed541fff",
    "transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

Transactions

A transaction represents 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, etc. Each transaction belongs to only one account.

Currently, the only aspect of a transaction that can be personalized is the description.

Update a transaction

Use this endpoint to update the description of a specific transaction according to its unique GUID.

Parameters

Parameter Required?
description Yes

Endpoint:

PUT /users/{user_guid}/transactions/{transaction_guid}

1
2
3
4
5
6
7
8
9

curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transactions/TRN-bb65493f-326c-4364-b79d-50829bd8277b' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key' \
-H 'Content-Type: application/json' \
-d '{
      "transaction": {
        "description": "new description"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

{
  "transaction": {
    "account_guid": "ACT-5ab76520-e0f8-434f-aedf-4f41b8b3ac6f",
    "account_id": "account-1040434698",
    "amount": 35.71,
    "category": "Shopping",
    "check_number_string": null,
    "created_at": "2020-08-18T20:15:36Z",
    "currency_code": null,
    "date": "2020-08-17",
    "description": "new description",
    "guid": "TRN-bb65493f-326c-4364-b79d-50829bd8277b",
    "id": "transaction-1040434568",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": true,
    "is_fee": false,
    "is_income": false,
    "is_international": null,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": false,
    "is_subscription": false,
    "latitude": null,
    "localized_description": null,
    "localized_memo": null,
    "longitude": null,
    "member_guid": "MBR-0b2121f5-bf4f-4244-a697-cac69160020f",
    "member_is_managed_by_user": true,
    "memo": null,
    "merchant_category_code": 0,
    "merchant_guid": "MCH-f07fcd23-1a18-a1a5-b49b-41d2b1076a69",
    "merchant_location_guid": null,
    "original_description": "Amazon.com*MF1S14RN0",
    "posted_at": "2020-08-17T11:00:00Z",
    "status": "POSTED",
    "top_level_category": "Shopping",
    "transacted_at": "2020-08-17T11:00:00Z",
    "type": "DEBIT",
    "updated_at": "2020-08-24T17:15:21Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "user-1040435626"
  }
}

Transaction rules

A transaction rule allows partners to specify a match_description and a category; all transactions matching the specified description will be placed in the chosen category.

Transaction rules override the default category MX gives to a transaction. Once a rule is created, all past transactions with a matching cleansed description are placed in the partner-chosen category, and any future transactions will be placed in the chosen category as well.

For example, creating a rule with the match_description “Wal-mart” and the category_guid for “Groceries” will automatically apply that category_guid to any transaction with a matching description, including both existing and future transactions.

Partners may also pr