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.
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 . |
MX Platform API requests must be HTTPS with encryption TLSv1.2 or higher or else they will fail.
Requests are authorized with a Basic
token which requires a client_id
and an api_key
.
The Basic
token is the URL-safe Base64 encoding of a string which contains both your client_id
and your api_key
separated by a colon. For example, where your client ID is CLIENT-1234
and your API key is API-KEY-4567
, your Basic
authorization token would be Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3
. See the example to the right.
The client_id
and api_key
for both the development and production environments are available in the client dashboard.
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.
In some instances, requests that require authentication will return 404 Not Found
, instead of 401 Unauthorized
. This is to prevent leaking private information.
Authorization header
Authorization: Basic {token}
Basic authorization token
Base64 encoding of:
{client_id}:{api_key}
Example
CLIENT-1234:API-KEY-4567 -> Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3
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
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.
Requests to the API must use characters encoded with the UTF-8 standard.
JSON structured data is expected in all requests and returned in all responses, including some errors.
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:23-06:00
.
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.
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 | 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 an aggregation on a member , an aggregation of the same type is already running; e.g., calling aggregate member while a previous aggregation is still running, or calling verify member while a previous verification is still running. |
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. |
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.",
}
}
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'
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.
The default minimum time between aggregation-type events (which includes account verification, balance requests, extended transaction requests, identity verification, and statement requests) is 10,800 seconds (3 hours), though this limit can vary by institution.
Aggregating within this limit will not return an error, however; the response will have a status of 202 Accepted
and contain the current state of the member
, including the latest connection_status
. Certain codepaths may bypass this limit.
The MX Bank test institution has no aggregation limits.
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.
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.
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.
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.
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 . |
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
}
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
.
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.
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 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. |
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 |
ui_message_version |
Use this to specify which version of postMessage events are triggered. All new implementations should use version 4. Prior versions are deprecated. | Integer | Connect |
ui_message_webview_url_scheme |
Used in postMessages and OAuth redirects in WebViews. Defaults to atrium . |
String | Connect |
update_credentials |
Loads widget to the update credential view of a current member. Optionally used with current_member_guid . |
Boolean | Connect |
wait_for_full_aggregation |
Loads connect normally, waits until the aggregation job is complete in order to fire the onSuccess postMessage to allow clients to have transactional data by the time the widget is closed. |
Boolean | Connect |
Endpoint:
POST /users/{user_guid}/widget_urls
Example request
1
2
3
4
5
6
7
8
9
10
11
curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"widget_url": {
"widget_type": "connect_widget",
"color_scheme": "dark",
"is_mobile_webview": true
}
}'
Example response
1
2
3
4
5
6
7
{
"widget_url": {
"type": "connect_widget",
"url": "https://int-widgets.moneydesktop.com/md/trends/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
"user_id": "U-jeff-201709221210"
}
}
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
Example request
1
2
3
4
5
6
7
8
9
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{
"config": {
"color_scheme": "dark"
}
}'
Example response
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"
}
}
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.
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.
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.
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. |
Get onSuccess 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 memberAdded postMessage that triggers the onSuccess postMessage. Ensuring that transactional data is available before moving on. |
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.
Do not include transaction data in the aggregation job after the user is connected
1
2
3
4
5
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{ "include_transactions": false }'
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.
Load MXConnect with the given institution
1
2
3
4
5
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{ "current_institution_code": {bank code} }'
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.
Load MXConnect with the given member
1
2
3
4
5
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{ "current_member_guid": {member_guid} }'
It is imperative that you correctly configure Connect when embedding in a WebView. See the WebView section for more information.
Setting the mode
to verification
will change several behaviors in Connect:
Load MXConnect in verification mode
1
2
3
4
5
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{ "mode": "verification" }'
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.
Wait for account, transaction, or verification data before finishing
1
2
3
4
5
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{ "wait_for_full_aggregation": true }'
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.
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 |
onLoad |
Function | An event message that is fired when the widget is loaded. | No |
onSuccess |
Function | An event message that is fired upon successfully adding a new member for the user |
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
<script src="https://atrium.mx.com/connect.js"></script>
<script>
var mxConnect = new MXConnect({
id: "addAccount",
url:
"https://int-widgets.moneydesktop.com/md/connect/jb1rA14m85tw2lyvpgfx4gc6d3Z8z8Ayb8",
onLoad: function () {
// Connect widget successfully loaded
console.log("On Load");
},
onSuccess: function (memberGuid) {
// Member created successfully
console.log("On Success");
},
});
var addAccountClick = function () {
mxConnect.load();
};
</script>
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 atrium://
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
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{
"is_mobile_webview": true,
"ui_message_version": 4,
"ui_message_webview_url_scheme": "yourAppScheme"
}'
# Possible navigation events based on the config above:
# `atrium://load`
# `yourAppScheme://connect/institutionSearch?metadata={...json...}
Java example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
public class MainActivity extends AppCompatActivity {
private WebView webView = null;
@Override
protected void onCreate(Bundle savedInstanceState) {
webView = (WebView) findViewById(R.id.webview);
webView.setWebViewClient(new AtriumWebViewClient());
webView.getSettings().setDomStorageEnabled(true);
webView.getSettings().setJavaScriptEnabled(true);
}
private class AtriumWebViewClient extends WebViewClient {
@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {
if (url.equals("atrium://mxConnectLoaded")) {
//Take action here.
return true;
} else if (url.startsWith("atrium://memberAdded")) {
//Grab member guid and take action here.
return true;
}
return false;
}
}
}
Swift example
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("atrium://"))! {
// Take action here
// Cancel request
decisionHandler(.cancel)
return
}
// Allow request
decisionHandler(.allow)
}
}
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.
Example request
1
2
3
4
5
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{ "is_mobile_webview": true, "ui_message_version": 4, "ui_message_webview_url_scheme": "{app scheme}" }'
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.
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 both 'mx', 'atrium' and whatever you configured
// ui_message_webview_url_scheme to be. In this example, it was 'appscheme'.
boolean isFromMX = url.startsWith("mx://") || url.startsWith("atrium://") || 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
60
/**
* 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://"
let atriumScheme = "atrium://"
func webView(_ webView: WKWebView,
decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {
// Ensure you are looking for schemes from both 'mx', 'atrium', 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 || url?.hasPrefix(atriumScheme) == 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)")
}
}
}
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.
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
}
}
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. |
selectMemeber |
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
}
Trigged when the app is loaded.
Widget load event
1
2
3
4
{
"type": "mx/load",
"mx": true
}
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"
}
}
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.
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 currently available for use in the account . The available balance will normally be a positive value for all account types. The value’s sign is determined in the same way as the balance field. |
available_credit |
Decimal | The amount of credit currently available for use in the account . |
balance |
Decimal | The balance associated with the account . The balance will normally be a positive value for all account types. For instance, 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 |
String | The day of the month the payment is due. For example, the 14th is passed as 14. |
death_benefit |
Decimal | 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 |
institution_code |
String | A unique identifier for the institution associated with this account . Defined by MX. |
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 |
String | 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 to which the account belongs, assigned by MX. |
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. Max length is 10,2. |
name |
String | The human-readable name for the account . |
original_balance |
Decimal | The original balance associated with the account . This will always be positive. |
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. |
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. Max length is 14,2. |
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 to which the account belongs. |
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 |
This endpoint returns a list of all the accounts associated with the specified user
.
Endpoint:
GET /users/{user_guid}/accounts
Example request:
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' \
-H 'Authorization: Basic {token}'
Example response:
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
{
"accounts": [
{
"account_number": null,
"apr": null,
"apy": null,
"available_balance": 1276.55,
"available_credit": null,
"balance": 1281.55,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2013-02-20T01:23:33Z",
"credit_limit": null,
"currency_code": null,
"day_payment_is_due": null,
"death_benefit": null,
"guid": "ACT-7ba8856c-1f2c-8dc9-21ac-db7a1f16cc8d",
"holdings_value": null,
"id": "19819",
"institution_code": "53486",
"interest_rate": 0,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-1347b7f1-2511-6cb6-257f-564d67b4aba7",
"minimum_balance": null,
"minimum_payment": 0,
"name": "Regular Shares",
"original_balance": 0,
"payment_due_at": null,
"payoff_balance": null,
"started_on": null,
"subtype": null,
"total_account_value": null,
"type": "SAVINGS",
"updated_at": "2016-04-19T22:26:39Z",
"user_guid": "USR-cad07537-a598-272b-a6cb-b15430f177d4"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 4,
"total_pages": 1
}
}
This endpoint returns the specified account
resource.
Endpoint:
GET /users/{user_guid}/accounts/{account_guid}
Example request
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' \
-H 'Authorization: Basic {token}'
Example response
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
{
"account": {
"account_number": null,
"apr": null,
"apy": null,
"available_balance": 1276.55,
"available_credit": null,
"balance": 1281.55,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2013-02-20T01:23:33Z",
"credit_limit": null,
"currency_code": null,
"day_payment_is_due": null,
"death_benefit": null,
"guid": "ACT-7ba8856c-1f2c-8dc9-21ac-db7a1f16cc8d",
"holdings_value": null,
"id": "19819",
"institution_code": "53486",
"interest_rate": 0,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-1347b7f1-2511-6cb6-257f-564d67b4aba7",
"minimum_balance": null,
"minimum_payment": 0,
"name": "Regular Shares",
"original_balance": 0,
"payment_due_at": null,
"payoff_balance": null,
"started_on": null,
"subtype": null,
"total_account_value": null,
"type": "SAVINGS",
"updated_at": "2016-04-19T22:26:39Z",
"user_guid": "USR-cad07537-a598-272b-a6cb-b15430f177d4"
}
}
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}
Example request
1
2
3
4
5
6
7
8
9
curl -L -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/accounts/ACT-82a93692-f756-534f-9b2e-ad10a0f38462' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"account": {
"is_hidden": true
}
}'
Example response
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
{
"account": {
"account_number": null,
"apr": null,
"apy": null,
"available_balance": 1276.55,
"available_credit": null,
"balance": 1281.55,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2013-02-20T01:23:33Z",
"credit_limit": null,
"currency_code": null,
"day_payment_is_due": null,
"death_benefit": null,
"guid": "ACT-7ba8856c-1f2c-8dc9-21ac-db7a1f16cc8d",
"holdings_value": null,
"id": "19819",
"institution_code": "53486",
"interest_rate": 0,
"is_closed": false,
"is_hidden": true,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-1347b7f1-2511-6cb6-257f-564d67b4aba7",
"minimum_balance": null,
"minimum_payment": 0,
"name": "Regular Shares",
"original_balance": 0,
"payment_due_at": null,
"payoff_balance": null,
"started_on": null,
"subtype": null,
"total_account_value": null,
"type": "SAVINGS",
"updated_at": "2016-04-19T22:26:39Z",
"user_guid": "USR-cad07537-a598-272b-a6cb-b15430f177d4"
}
}
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.
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 . |
This endpoint returns a list containing institutions that have been set as the partner’s favorites, sorted by popularity. These responses are not paginated.
Pleaase contact MX to set a list of favorites.
Endpoint:
GET /institutions/favorites
Example request:
1
2
3
4
curl -X GET https://int-api.mx.com/institutions/favorites
2bab47 \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response:
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
{
"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"
},
...
]
}
Endpoint:
GET /institutions/{institution_code}/credentials
Example request
1
2
3
curl -X GET https://int-api.mx.com/institutions/mxbank/credentials \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"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"
}
]
}
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
Example request:
1
2
3
curl -X GET https://int-api.mx.com/institutions \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response:
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' \
-H 'Authorization: Basic {token}'
Example response with query parameters:
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
}
}
This endpoint returns information about the institution specified by institution_code
.
Endpoint:
GET /institutions/{institution_code}
Example request:
1
2
3
4
curl -X GET https://int-api.mx.com/institutions/50025
2bab47 \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response:
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"
}
}
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.
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. |
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. |
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 {…}. |
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
Example request:
1
2
3
4
curl -L -X POST 'https://int-api.mx.com/users/USR-1234/members/MBR-5678/aggregate' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"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,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
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
Example request:
1
2
3
4
curl -L -X POST 'https://int-api.mx.com/users/USR-1234/members/MBR-5678/check_balance' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"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,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
This endpoint allows you to create a new member
. Members are created with the required parameters credentials
and institution_code
, and the optional parameters id
and metadata
.
When creating a 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 /institutions/{institution_code}/credentials
endpoint.
If successful, The API will respond with the newly-created member
object.
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 |
Endpoint:
POST /users/{user_guid}/members
Example request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
-H 'Authorization: Basic YXBpX3Rlc3Q6OVk4c0FjSWFCZ0lwcHBHcGtTR3JFcHMxVG52elFDQ05Zcm51MkdmbS1CRQ==' \
-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"
}
}'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"member": {
"aggregated_at": null,
"connection_status": "CREATED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
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}
Example request
1
2
3
4
curl -i -X DELETE https://int-api.mx.com/users/USR-1234/members/MBR-4567
2bab47 \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
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
Example request:
1
2
3
4
curl -X GET https://int-api.mx.com/users/USR-1234/members/MBR-1234/challenges
2bab47 \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response:
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
{
"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"
}
]
}
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 . |
options |
Array | See explanation below. |
For credentials with the type OPTIONS
, the credentials
object will contain a nested array called options
. This array lists various choices available for credential prompts, and includes further attributes.
Options fields | Data type | Description |
---|---|---|
label |
String | A label for the credential prompt. |
value |
String | A response for the credential prompt. |
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
Example request:
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/credentials' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"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"
}
]
}
This endpoint returns a list of all the members that belong to the specified user
.
Endpoint:
GET /users/{user_guid}/members
Example request:
1
2
3
curl -X GET https://int-api.mx.com/users/USR-1234/members \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response:
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
{
"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,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
},
{
"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,
"metadata": null,
"name": "Capital One ",
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
},
{
"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,
"metadata": null,
"name": "PayPal",
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 3,
"total_pages": 1
}
}
This endpoint returns information about the specified member
.
Endpoint:
GET /users/{user_guid}/members/{member_guid}
Example request:
1
2
3
4
curl -X GET https://int-api.mx.com/users/USR-1234/members/MBR-4567
2bab47 \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"member": {
"aggregated_at": "2019-12-03T18:10:22Z",
"connection_status": "FAILED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": false,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
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 togather to get a picture of what is happening with the member
.
Endpoint:
GET /users/{user_guid}/members/{member_guid}/status
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic YXBpX3Rlc3Q6OVk4c0FjSWFCZ0lwcHBHcGtTR3JFcHMxVG52elFDQ05Zcm51MkdmbS1CRQ=='
Example response
1
2
3
4
5
6
7
8
9
10
{
"member": {
"aggregated_at": "2020-05-07T22:01:00Z",
"connection_status": "FAILED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"is_authenticated": false,
"is_being_aggregated": false,
"successfully_aggregated_at": "2019-08-08T16:17:51Z"
}
}
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
Example request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
curl -L -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/resume' \
-H 'Authorization: Basic {token}' \
-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"
}
]
}
}'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"member": {
"aggregated_at": "2020-04-29T20:40:07Z",
"connection_status": "RESUMED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
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 |
institution_code |
String | The unique identifier for the institution associated with the member . Defined by MX. |
No |
is_oauth |
Boolean | This indicates whether the member uses Oauth authentication. | No |
metadata |
String | Additional information you can store on this member . |
No |
Endpoint:
PUT /users/{user_guid}/members/{member_guid}
Example request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl -L -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0' \
-H 'Authorization: Basic YXBpX3Rlc3Q6OVk4c0FjSWFCZ0lwcHBHcGtTR3JFcHMxVG52elFDQ05Zcm51MkdmbS1CRQ==' \
-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\"}"
}
}'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"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": true,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
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
.
Field | Data type | Description |
---|---|---|
account_guid |
String | The unique identifier for the account associated with the transaction . Defined by MX. |
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 field is only returned with partner-managed transactions. |
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. |
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. |
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. |
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
* 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 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 |
Requests to this endpoint return a list of transactions associated with the specified member
, accross all accounts associated with that member
.
Endpoint:
GET /users/{user_guid}/members/{member_guid}/transactions
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/transactions' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
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
{
"transactions": [
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"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",
"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,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"memo": null,
"merchant_category_code": null,
"merchant_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"
},
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"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",
"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,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"memo": null,
"merchant_category_code": null,
"merchant_guid": "MCH-a5252ab5-56bc-a0ea-7d89-e598a4d5ec0e",
"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"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 20,
"total_pages": 1
}
}
Requests to this endpoint return a list of transactions associated with the specified user
, accross all members and accounts associated with that user
.
Endpoint:
GET /users/{user_guid}/transactions
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transactions' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response
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
{
"transactions": [
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"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",
"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,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"memo": null,
"merchant_category_code": null,
"merchant_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"
},
{
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"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",
"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,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"memo": null,
"merchant_category_code": null,
"merchant_guid": "MCH-a5252ab5-56bc-a0ea-7d89-e598a4d5ec0e",
"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"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 20,
"total_pages": 1
}
}
Requests to this endpoint will return the attributes of the specified transaction
.
Endpoint:
GET /users/{user_guid}/transactions/{transaction_guid}
Example request
1
2
3
curl -L -X GET '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' \
-H 'Authorization: Basic {token}'
Example response
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
{
"transaction": {
"account_guid": "ACT-09c0ee66-51a8-4edf-b977-99534a471134",
"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",
"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,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225",
"memo": null,
"merchant_category_code": null,
"merchant_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"
}
}
A user
represents a person using the MX Platform API via your application, be it a mobile app, web app, desktop app, etc.
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. |
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. Users who are disabled for the entirety of a billing period will not be factored into that month’s bill.
Parameters
Field | Data type | Required? |
---|---|---|
email |
String | No |
id |
String | No |
is_disabled |
Boolean | No |
metadata |
String | No |
Endpoint:
POST /users
Example request
1
2
3
4
5
6
7
8
9
10
11
12
curl -L -X POST 'https://int-api.mx.com/users' \
-H 'Authorization: Basic {token}' \
-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"
}
}'
Example response
1
2
3
4
5
6
7
8
9
{
"user": {
"email": "totally.fake.email@notreal.com",
"guid": "USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2",
"id": "partner-2345",
"is_disabled": false,
"metadata": "Yada yada yada"
}
}
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}
Example request
1
2
3
curl -L -X DELETE https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53 \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Requests to this endpoint will return a list of all your users.
Endpoint:
GET /users
Example request
1
2
3
curl -L -X GET https://int-api.mx.com/users \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response
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
}
}
Requests to this endpoint will return the details of the specified user
.
Endpoint:
GET /users/{user_guid}
"Example request
1
2
3
curl -L -X GET https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53 \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'
Example response
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
}
}
This endpoint retuns a URL which will load the MX Connect widget in the specified configuration. Configuration options can be passed in the request body nested under a config
object.
Configuration options
Option | Data type | Description |
---|---|---|
color_scheme |
String | Load the Connect widget in the specified color_scheme ; options are light and dark . Defaults to light . |
current_institution_code |
String | Load the widget into the credential view for the specified institution. |
current_institution_guid |
String | Load the widget into the credential view for the specified institution. |
current_member_guid |
String | Load to a specific member that contains an error or requires MFA from the most recent job. Members with no errors will return to search. current_member_guid takes precedence over current_institution_code . |
disable_institution_search |
Boolean | When set to true , the institution search feature will be disabled and end users will not be able to navigate to it. |
include_transactions |
Boolean | 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 . |
is_mobile_webview |
Boolean | Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages. |
mode |
String | Loads the Connect widget into a specified mode; options are verification and aggregation . Defaults to aggregation . |
ui_message_version |
String | Use this to specify which version of postMessage events are triggered. All new implementations should use version 4. Prior versions are deprecated. |
ui_message_webview_url_scheme |
String | Used in postMessages and OAuth redirects in WebViews. Defaults to atrium . |
update_credentials |
Boolean | Loads widget to the update credential view of a current member. Optionally used with current_member_guid . |
wait_for_full_aggregation |
Boolean | Loads connect normally, waits until the aggregation job is complete in order to fire the onSuccess postMessage to allow clients to have transactional data by the time the widget is closed. |
Configuration scenarios
Below are several scenarios which partners may wish to present to end users, along with the correct configuration settings for each situation.
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. |
Get onSuccess 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 memberAdded postMessage that triggers the onSuccess postMessage. Ensuring that transactional data is available before moving on. |
Endpoint:
POST /users/{user_guid}/connect_widget_url
Example request
1
2
3
4
5
6
7
8
9
curl -L -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' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{
"config": {
"color_scheme": "dark"
}
}'
Example response
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"
}
}
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}
Example request
1
2
3
4
5
6
7
8
9
curl -L -X PUT https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53 \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}' \
-H 'Content-type: application/json' \
-d '{
"user": {
"id": "ironman2"
}
}'
Example response
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
}
}
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.
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.
Parameters
Field Name | Required? |
---|---|
amount |
No |
description |
Yes |
id |
Yes |
merchant_category_code |
No |
type |
No |
Endpoint:
POST /transactions/enhance
Example request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -L -X POST 'https://int-api.mx.com/transactions/enhance' \
-H 'Authorization: Basic YXBpX3Rlc3Q6OVk4c0FjSWFCZ0lwcHBHcGtTR3JFcHMxVG52elFDQ05Zcm51MkdmbS1CRQ==' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d'{
"transactions": [
{
"amount": 11.22,
"description": "BEER BAR 65000000764SALT LAKE C",
"id": "12",
"type": "DEBIT"
}
]
}'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"transactions": [
{
"amount": 11.22,
"category": "Alcohol & Bars",
"description": "Beer Bar",
"id": "12",
"is_bill_pay": null,
"is_direct_deposit": false,
"is_expense": null,
"is_fee": null,
"is_income": false,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": null,
"merchant_category_code": null,
"merchant_guid": null,
"original_description": "BEER BAR 65000000764SALT LAKE C",
"type": null
}
]
}
A merchant
contains information about the merchant, business, company, or seller associated with a specific transaction
. This information includes a name, logo, and website.
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 . |
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 . |
This endpoint returns a paginated list of all the merchants in the MX system.
Endpoint:
GET /merchants
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/merchants' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
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
{
"merchants": [
{
"created_at": "2018-09-17T19:13:53Z",
"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",
"updated_at": "2019-10-28T21:05:54Z",
"website_url": "https://www.1800contacts.com"
},
{
"created_at": "2018-07-16T16:31:35Z",
"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",
"updated_at": "2019-10-28T21:04:40Z",
"website_url": "https://www.1800flowers.com"
},
...
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 4791,
"total_pages": 192
}
}
This endpoint returns the attributes of the specified merchant
.
Endpoint:
GET /merchants
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/merchants/MCH-ad6d3405-ec03-721d-b0ca-eeceeebcb8b5' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
1
2
3
4
5
6
7
8
9
10
{
"merchant": {
"created_at": "2018-09-17T19:13:53Z",
"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",
"updated_at": "2019-10-28T21:05:54Z",
"website_url": "https://www.1800contacts.com"
}
}
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.
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. |
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. |
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.
Endpoint:
POST /users/{user_guid}/members/{member_guid}/identify
Example request
1
2
3
4
curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/identify' \
-H 'Authorization: Basic YXBpX3Rlc3Q6OVk4c0FjSWFCZ0lwcHBHcGtTR3JFcHMxVG52elFDQ05Zcm51MkdmbS1CRQ==' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"member": {
"aggregated_at": "2020-05-22T22:18:04Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": "partner-member-12345",
"institution_code": "mxbank",
"is_being_aggregated": true,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
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 each account associated with the member
.
Endpoint:
GET /users/{user_guid}/members/{member_guid}/account_owners
Example request
1
2
3
curl -L -X GET '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' \
-H 'Authorization: Basic {token}'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"account_owners": [
{
"account_guid": "ACT-123",
"address": "123 This Way",
"city": "Middlesex",
"country": "US",
"email": "donnie@darko.co",
"guid": "ACO-123",
"member_guid": "MBR-123",
"owner_name": "Donnie Darko",
"phone": "555-555-5555",
"postal_code": "00000-0000",
"state": "VA",
"user_guid": "USR-123"
}
]
}
Holdings represent a stock, bond, or other type of investment.
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 . |
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 |
This endpoint returns all holdings associated with the specified member
across all accounts.
Endpoint:
GET /users/{user_guid}/members/{member_guid}/holdings
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-a2e65785-975d-dcbd-fd22-7bbba2581fb0/members/MBR-3eb08fde-01d5-454c-ae6a-95606ccd1225/holdings' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
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
}
}
This endpoint returns all holdings associated with the specified user
accross all accounts and members.
Endpoint:
GET /users/{user_guid}/holdings
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/holdings' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
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
}
}
This endpoint returns all holdings associated with the specified account
.
Endpoint:
GET /users/{user_guid}/holdings/{holding_guid}
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/holdings/HOL-57ffa88f-f630-4232-991e-4f82a783f24e' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
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"
}
}
Tags allow partners and end users to create a custom label for particular transactions.
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. |
Use this endpoint to create a new custom tag.
Parameters
Parameter | Required? |
---|---|
name |
Yes |
Endpoint:
POST /users/{user_guid}/tags
Example request
1
2
3
4
5
6
7
8
9
curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"tag": {
"name": "MY TAG"
}
}'
Example response
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"
}
}
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}
Example request
1
2
3
curl -L -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags/TAG-aef36e72-6294-4c38-844d-e573e80aed52' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
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
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[
{
"tag": {
"guid": "TAG-847349e2-9b27-6d25-c3b5-404b2cfc562f",
"name": "Business",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
},
{
"tag": {
"guid": "TAG-40faf068-abb4-405c-8f6a-e883ed541fff",
"name": "MY OTHER TAG",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
]
Use this endpoint to read the attributes of a particular tag according to its unique GUID.
Endpoint:
GET /users/{user_guid}/tags/{tag_guid}
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags/TAG-aef36e72-6294-4c38-844d-e573e80aed52' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
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"
}
}
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}
Example request
1
2
3
4
5
6
7
8
9
curl -L -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags/TAG-aef36e72-6294-4c38-844d-e573e80aed52' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"tag": {
"name": "New Tag Name"
}
}'
Example response
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 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.
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. |
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
Example request
1
2
3
4
5
6
7
8
9
10
curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"tagging": {
"tag_guid": "TAG-40faf068-abb4-405c-8f6a-e883ed541fff",
"transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4"
}
}'
Example response
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"
}
}
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}
Example request
1
2
3
curl -L -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/TGN-007f5486-17e1-45fc-8b87-8f03984430fe' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Use this endpoint to retrieve a list of all the taggings associated with a specific user
.
Endpoint:
GET /users/{user_guid}/taggings
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
1
2
3
4
5
6
7
8
9
10
11
{
"taggings": [
{
"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"
}
]
}
Use this endpoint to read the attributes of a tagging
according to its unique GUID.
Endpoint:
GET /users/{user_guid}/taggings/{tagging_guid}
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/TGN-007f5486-17e1-45fc-8b87-8f03984430fe' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
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"
}
}
Use this endpoint to update a tagging.
Parameters
Parameter | Required? |
---|---|
tag_guid |
Yes |
Endpoint:
PUT /users/{user_guid}/taggings/{tagging_guid}
Example request
1
2
3
4
5
6
7
8
9
curl -L -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/TGN-007f5486-17e1-45fc-8b87-8f03984430fe' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"tagging": {
"tag_guid": "TAG-8ff0ec57-4628-4c7d-86ed-4e0cd78e2971"
}
}'
Example response
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"
}
}
Account verification allows you to access account and routing numbers for accounts associated with a particular member
. The process for account verification is much like standard aggregation.
The verify endpoint may be used to gather this information on certain institutions, and then it can be accessed with another call to the account numbers endpoint.
Field | Data type | Description |
---|---|---|
account_guid |
String | The unique identifier for the account associated with a particular set of account and routing numbers. Defined by MX. |
account_number |
String | The banking account number associated with a particular account. |
institution_number |
String | The three-digit number identifying a Canadian banking institution. |
member_guid |
String | The unique identifier for the member associated with a particular set of account and routing numbers. Defined by MX. |
routing_number |
String | The routing number for the financial institution associated with the account. |
transit_number |
String | The five-digit number identifying the branch of a Canadian financial institution. |
user_guid |
String | The unique identifier for the user associated with a particular set of account and routing numbers. Defined by MX. |
This endpoint returns a list of account numbers associated with the specified account
.
Endpoint:
GET /users/{user_guid}/accounts/{account_guid}/account_numbers
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-82a93692-f756-534f-9b2e-ad10a0f38462/account_numbers' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"account_numbers": [
{
"account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"account_number": "10001",
"institution_number": null,
"member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"routing_number": "68899990000000",
"transit_number": null,
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}
This endpoint returns a list of account numbers associated with the specified member
.
Endpoint:
GET /users/{user_guid}/members/{member_guid}/account_numbers
Example request
1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/account_numbers' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic YXBpX3Rlc3Q6OVk4c0FjSWFCZ0lwcHBHcGtTR3JFcHMxVG52elFDQ05Zcm51MkdmbS1CRQ=='
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"account_numbers": [
{
"account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"account_number": "10001",
"institution_number": null,
"member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"routing_number": "68899990000000",
"transit_number": null,
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}
The verify endpoint begins a verification process for a member
.
The verification workflow is similar to standard aggregation: Start the verification, check the connection status
, answer MFA if necessary check the status again, then read the member’s account numbers.
If a verification 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.
Endpoint:
GET /users/{user_guid}/members/{member_guid}/verify
Example request
1
2
3
4
curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/verify' \
-H 'Authorization: Basic YXBpX3Rlc3Q6OVk4c0FjSWFCZ0lwcHBHcGtTR3JFcHMxVG52elFDQ05Zcm51MkdmbS1CRQ==' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'
Example response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"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,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": "2019-08-08T16:17:51Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
MX offers a suite of digital money management software. It consists of several widgets, each of which can be displayed alone or in conjunction with other widgets. This allows for a customizable and configurable product that fits the needs of both MX’s partners and their end users.
Widgets are designed to work seamlessly in either a mobile or desktop environment while using a single codebase. Most widgets are built with a responsive design using the React Javascript framework.
The API is currently limited to the Connect widget. However, you will soon be able to request a wide range of fully-featured widgets to embed in a website, online banking portal, or mobile app.
Getting a widget in a specific language requires passing the desired language as a parameter in the Accept-Language
header with requests to the get widget URL endpoint.
If no header is provided, widgets will default to en-US
.
Only some widgets are currently available in multiple languages.
Supported languages and widgets
Language | Widget |
---|---|
en-CA |
All |
en-US |
All |
fr |
accounts_widget, connect_widget, pulse_widget |
fr-CA |
accounts_widget, connect_widget, pulse_widget |
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. Partners may also pass an optional Accept-Language
header.
Currently, only the Connect widget can be accessed through the MX Platform API. Other widget types will be added soon. Use the widget type connect_widget
to request Connect.
Note that this is a POST
request.
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. |
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 |
ui_message_version |
Use this to specify which version of postMessage events are triggered. All new implementations should use version 4. Prior versions are deprecated. | Integer | Connect |
ui_message_webview_url_scheme |
Used in postMessages and OAuth redirects in WebViews. Defaults to atrium . |
String | Connect |
update_credentials |
Loads widget to the update credential view of a current member. Optionally used with current_member_guid . |
Boolean | Connect |
wait_for_full_aggregation |
Loads connect normally, waits until the aggregation job is complete in order to fire the onSuccess postMessage to allow clients to have transactional data by the time the widget is closed. |
Boolean | Connect |
Endpoint:
POST /users/{user_guid}/widget_urls
Example request
1
2
3
4
5
6
7
8
9
curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"widget_url": {
"widget_type": "connect_widget"
}
}'
Example response
1
2
3
4
5
6
7
{
"widget_url": {
"type": "connect_widget",
"url": "https://int-widgets.moneydesktop.com/md/trends/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
"user_id": "U-jeff-201709221210"
}
}
MX provides webhooks that send HTTPS POST callback requests to the URL of your choice. This enables you to subscribe to certain events, be notified when those events occur, and have information related to that event delivered to you. If you are subscribed to multiple events, a different URL can be configured for each event.
You can set up and configure webhooks on the client dashboard.
The current version of webhooks in the MX Platform API has the following features:
All webhook requests are encrypted by default. However, MX recommends using an additional layer of security as well. One or more of the following are typical:
MX webhooks will automatically retry a request in the case of a failed delivery such as a connection timeout, write timeout, read timeout, DNS error, etc.
The schedule of retries incorporates randomness so as to avoid a flood of requests to your system. Retries decrease in frequency with each attempt. You can expect to see a number of retries within the first hour of the initial attempt; gradually, retries will become less frequent.
If the webhook cannot be successfully delivered after 12 successive retries, it will not be delivered.
Example retry schedule
Retry number | Time elapsed since initial attempt |
---|---|
1 | 0h 0m 30s |
2 | 0h 1m 16s |
3 | 0h 2m 32s |
4 | 0h 5m 8s |
5 | 0h 10m 54s |
6 | 0h 23m 4s |
7 | 0h 46m 40s |
8 | 1h 28m 56s |
9 | 2h 39m 42s |
10 | 4h 31m 48s |
11 | 7h 21m 28s |
12 | 11h 28m 44s |
Partners can signal an error to MX’s webhooks by returning any status code other than those listed below. Any status code returned to MX that is not listed below will be considered an error by the webhook system. The most common error codes are those within the 400 range (something in the request was invalid) or the 500 range (something went wrong on the receiving end).
Successful status codes
200 OK
201 CREATED
202 ACCEPTED
203 NON_AUTHORITATIVE_INFORMATION
204 NO_CONTENT
205 RESET_CONTENT
206 PARTIAL_CONTENT
To set up and configure webhooks or test an existing webhook, please visit your webhook profile on the client dashboard.
A partner subscribed to the connection status webhook will be notified whenever a member’s connection_status
field enters into an end-user-actionable state.
The following connection statuses will trigger this webhook:
CHALLENGED
DENIED
EXPIRED
IMPAIRED
IMPEDED
LOCKED
PREVENTED
REJECTED
Fields for the connection status webhook
Field | Data type | Definition |
---|---|---|
action |
String | This value should always equal CHANGED . |
connection_status |
String | This field indicates the state of a member’s aggregation, provided as a string. |
connection_status_id |
Integer | This field indicates the state of a member’s aggregation, provided as an integer. |
connection_status_message |
String | A message that can be displayed to the end user to help them navigate the connection and aggregation process. |
member_guid |
String | Unique identifier for the member that triggered the webhook. Defined by MX. |
type |
String | The type of webhook being delivered. |
user_guid |
String | The unique identifier for the user with which the member is associated. Defined by MX. |
Example payload:
1
2
3
4
5
6
7
8
9
{
"action": "CHANGED",
"connection_status": "CHALLENGED",
"connection_status_id": 3,
"connection_status_message": "To authenticate your connection to Chase Bank, please answer the following challenge(s).",
"member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
"type": "CONNECTION_STATUS",
"user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}
A partner subscribed to the aggregation webhook will be notified when any new data is available after a successful aggregation. The webhook will include a count of new transactions and updated transactions.
These webhooks fire only after a completed aggregation, including background aggregations. Actions performed on the member
through other endpoints will not trigger the webhook.
Fields for aggregation webhooks
Field | Data type | Description |
---|---|---|
action |
String | The action that triggered the webhook, e.g., member_data_updated . |
completed_at |
Integer | The date and time at which the process that triggered the webhook was finished. Given in Unix time. |
completed_on |
String | The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp. |
member_guid |
String | The unique identifier for the member which has new or updated transaction data. Defined by MX. |
transactions_created_count |
Integer | The number of newly created transactions. |
transactions_updated_count |
Integer | The number of newly updated transactions. |
type |
String | The type of webhook being delivered. Current possible values are AGGREGATION , BALANCE , HISTORY , and STATEMENT ; however, additional values may be added at any time. |
user_guid |
String | Unique identifier for the user with which the data is associated. Defined by MX. |
Example payload
1
2
3
4
5
6
7
8
9
10
{
"action": "member_data_updated",
"completed_at": 1531947410,
"completed_on": "2018-07-18",
"member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
"transactions_created_count": 3,
"transactions_updated_count": 2,
"type": "AGGREGATION",
"user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}
A partner subscribed to the balance webhook will be notified when any new data is available after a successful balance fetch. The webhook will include a count of new transactions and updated transactions.
These webhooks fire only after a completed balance fetch. Actions performed on the member
through other endpoints will not trigger the webhook.
Fields for balance webhooks
Field | Data type | Description |
---|---|---|
action |
String | The action that triggered the webhook, e.g., member_data_updated . |
completed_at |
Integer | The date and time at which the process that triggered the webhook was finished. Given in Unix time. |
completed_on |
String | The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp. |
memer_guid |
String | The unique identifier for the member which has new or updated transaction data. Defined by MX. |
type |
String | The type of webhook being delivered. Current possible values are AGGREGATION , BALANCE , HISTORY , and STATEMENT ; however, additional values may be added at any time. |
user_guid |
String | Unique identifier for the user with which the data is associated. Defined by MX. |
Example payload
1
2
3
4
5
6
7
8
{
"action": "member_data_updated",
"completed_at": 1531947410,
"completed_on": "2018-07-18",
"member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
"type": "BALANCE",
"user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}
A partner subscribed to the history webhook will be notified when any new data is available after a successful history fetch. The webhook will include a count of new transactions and updated transactions.
These webhooks fire only after a completed history fetch. Actions performed on the member
through other endpoints will not trigger the webhook.
Fields for history webhooks
Field | Data type | Description |
---|---|---|
action |
String | The action that triggered the webhook, e.g., member_data_updated . |
completed_at |
Integer | The date and time at which the process that triggered the webhook was finished. Given in Unix time. |
completed_on |
String | The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp. |
member_guid |
String | The unique identifier for the member which has new or updated transaction data. Defined by MX. |
transactions_created_count |
Integer | The number of newly created transactions. |
transactions_updated_count |
Integer | The number of newly updated transactions. |
type |
String | The type of webhook being delivered. Current possible values are AGGREGATION , BALANCE , HISTORY , and STATEMENT ; however, additional values may be added at any time. |
user_guid |
String | Unique identifier for the user with which the data is associated. Defined by MX. |
Example payload
1
2
3
4
5
6
7
8
9
10
{
"action": "member_data_updated",
"completed_at": 1531947410,
"completed_on": "2018-07-18",
"member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
"transactions_created_count": 3,
"transactions_updated_count": 2,
"type": "HISTORY",
"user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}
A partner subscribed to the statement webhook will be notified when any new data is available after a successful statement fetch. The webhook will include a count of new statements.
These webhooks fire only after a completed statement fetch. Actions performed on the member
through other endpoints will not trigger the webhook.
Fields for statement webhooks
Field | Data type | Description |
---|---|---|
action |
String | The action that triggered the webhook, e.g., member_data_updated . |
completed_at |
Integer | The date and time at which the process that triggered the webhook was finished. Given in Unix time. |
completed_on |
String | The date on which the process that triggered the webhook was finished. Given in ISO 8601 without a timestamp. |
member_guid |
String | The unique identifier for the member which has new or updated transaction data. Defined by MX. |
statements_created_count |
Integer | The number of newly created transactions. |
type |
String | The type of webhook being delivered. Current possible values are AGGREGATION , BALANCE , HISTORY , and STATEMENT ; however, additional values may be added at any time. |
user_guid |
String | Unique identifier for the user with which the data is associated. Defined by MX. |
Example payload
1
2
3
4
5
6
7
8
9
{
"action": "member_data_updated",
"completed_at": 1531947410,
"completed_on": "2018-07-18",
"member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
"statements_created_count": 3,
"type": "STATEMENT",
"user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e"
}
Date | Documentation version | Reference number | Description of changes |
---|---|---|---|
2021.01.14 | 2020.001 | P-151 | Added:
|
2021.01.12 | 2020.000 | P-147 | Changed:
|
2020.12.18 | 2020.002 | P-141 | Changed:
|
2020.12.18 | 2020.001 | P-140 | Added:
|
2020.12.11 | 2020.000 | P-138 | Added:
|