Introduction

The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions.

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

API architecture and resource structure

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

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

Authentication and security

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

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

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

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

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

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

Basic authorization value

Base64 encoding of:
client_id:api_key

Example

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

Base URL

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

Development URL

https://int-api.mx.com

Production URL

https://api.mx.com

Caching

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

Character encoding

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

Data format

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

Dates and times

Dates and times are always given in ISO 8601 format.

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

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

Deleting objects

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

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

Errors

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

Status codes

Status	Explanation
2xx Success
`200 OK`	Everything worked as expected with content returned.
`202 Accepted`	Everything worked and MX’s system is processing the request. When attempting a job on a `member`, a job of the same type is already running; e.g., calling aggregate member while a standard agg is still running, or calling verify member while a previous verification is still running. A standard aggregation has been attempted within the default minimum time between standard aggs.
`204 No Content`	Everything worked as expected without content returned.
4xx Requester error
`400 Bad Request`	Often, this means a required parameter was missing.
`401 Unauthorized`	Invalid MX-API-Key or MX-Client-ID provided.
`403 Forbidden`	The request was made from a non-whitelisted address or the feature is not available to the client.
`404 Not Found`	Invalid item/id/URL requested.
`405 Method Not Allowed`	A constraint on the requested endpoint wasn’t met.
`406 Not Acceptable`	The request didn’t specify a valid API version.
`409 Conflict`	1. An object with the given attributes already exists. 2. When attempting an aggregation on a `member`, the `member` already has an an aggregation of a different type running; e.g., calling the verify endpoint while a standard aggregation is already running, or calling fetch statements while an identification aggregation is already running.
`422 Unprocessable Entity`	The data provided cannot be processed.
5xx Responder error — which are rare
`500, 502, 504 Server errors`	Something went wrong with MX’s servers.
`503 Service Unavailable`	The MX Platform is being updated.

Example error message

1
2
3
4
5
{
  "error": {
    "message": "Unrecognized institution.",
  }
}

Headers

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

'Content-Type: application/json'

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

Identifiers and metadata

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

Do not store sensitive information as metadata.

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

Limits on the API

Aggregation throttling

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

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

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

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

Data availability

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

Request rate limits

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

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

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

User and member limits

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

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

OAuth

MX encourages partners to use OAuth for authenticating with financial institutions. However, some institutions support OAuth, while others don’t. And some institutions only support OAuth and no other forms of authentication.

Furthermore, using OAuth requires you to register with institutions that support OAuth to ensure security and trustworthiness. This registration can only be done after MX has granted you production access; MX will handle this registration on your behalf. You can request production access and OAuth registration on the dashboard.

If you have production access but have not yet been registered with the institutions that support OAuth, these institutions will not be returned in any institution-related endpoints.

This also means that there is only one OAuth institution available in the integration environment: mx_bank_oauth. You’ll have to use this for all OAuth development and testing in the integration environment.

Pagination

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

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

Query parameters

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

Pagination fields

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

Example pagination object

1
2
3
4
5
6
"pagination": {
  "current_page": 1,
  "per_page": 25,
  "total_entries": 2,
  "total_pages": 1
}

Versioning

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

The Connect widget

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

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

Request a Connect URL

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

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

Note that this is a POST request.

Configuration options

Configuration option	Description	Type	Widget
`color_scheme`	Load the Connect widget in the specified `color_scheme`; options are `light` and `dark`. Defaults to `light`.	String	Connect
`current_institution_code`	Load the widget into the credential view for the specified institution.	String	Connect
`current_institution_guid`	Load the widget into the credential view for the specified institution.	String	Connect
`current_member_guid`	Load to a specific member that contains an error or requires MFA from the most recent job. `current_member_guid` takes precedence over `current_institution_code`.	String	Connect
`disable_institution_search`	When set to `true`, the institution search feature will be disabled and end users will not be able to navigate to it. Must be used with `current_institution_code`, `current_instituion_guid`, or `current_member_guid`.	Boolean	Connect
`include_transactions`	When set to `false` while creating or updating a member, transaction data will not be automatically aggregated. Future manual or background aggregations will not be affected. Defaults to `true`.	Boolean	Connect
`is_mobile_webview`	Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages.	Boolean	All
`mode`	Loads the Connect widget into a specified mode; options are `verification` and `aggregation`. Defaults to `aggregation`.	String	Connect
`oauth_referral_source`	This determines how MX will respond to the result of an OAuth flow. When set to `APP`, MX will redirect to the URI specified in the `ui_message_webview_url_scheme`. When set to `BROWSER`, MX will send a postMessage but not redirect. If `is_mobile_webview` is `true`, this defaults to `APP`. If `false`, it defaults to `BROWSER`. See this guide for more details.	String	Connect
`ui_message_version`	Use this to specify which version of postMessage events are triggered. All new implementations must use version 4. Prior versions are deprecated.	Integer	Connect
`ui_message_webview_url_scheme`	Used in postMessages and OAuth redirects in WebViews. Defaults to `mx`.	String	Connect
`update_credentials`	Loads widget to the update credential view of a current member. Optionally used with `current_member_guid`. This option should be used sparingly. The best practice is to use `current_member_guid` and let the widget resolve the issue.	Boolean	Connect
`wait_for_full_aggregation`	Loads Connect, but forces the widget to wait until any aggregation-type process is complete in order to fire a member connected postMessage. This allows clients to have transactional data by the time the widget is closed.	Boolean	Connect
`widget_type`	Use this to specify which widget you would like to load.	String	Connect

Endpoint:

POST /users/{user_guid}/widget_urls

1
2
3
4
5
6
7
8
9
10
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
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const requestBody = {
  widget_url: {  
    color_scheme: 'light',
    current_institution_code: 'chase',
    current_institution_guid: 'INS-f1a3285d-e855-b61f-6aa7-8ae575c0e0e9',
    current_member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    disable_institution_search: false,
    include_transactions: true,
    is_mobile_webview: true,
    mode: 'aggregation',
    ui_message_version: 4,
    ui_message_webview_url_scheme: 'mx',
    update_credentials: false,
    wait_for_full_aggregation: false,
    widget_type: 'connect_widget'
  }
};
const acceptLanguage = 'en-US';

const response = await client.requestWidgetURL(userGuid, requestBody, acceptLanguage);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  accept_language: 'en-US'
}
request_body = ::MxPlatformRuby::WidgetRequestBody.new(
  widget_url: ::MxPlatformRuby::WidgetRequest.new(  
    color_scheme: 'light',
    current_institution_code: 'chase',
    current_institution_guid: 'INS-f1a3285d-e855-b61f-6aa7-8ae575c0e0e9',
    current_member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    disable_institution_search: false,
    include_transactions: true,
    is_mobile_webview: true,
    mode: 'aggregation',
    ui_message_version: 4,
    ui_message_webview_url_scheme: 'mx',
    update_credentials: false,
    wait_for_full_aggregation: false,
    widget_type: 'connect_widget'
  )
)

begin
  response = mx_platform_api.request_widget_url(user_guid, request_body, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_widget_url: #{e}"
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
curl -i -X POST 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/widget_urls' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: en-US' \
  -u 'client_id:api_key' \
  -d '{      
        "widget_url": {        
          "color_scheme": "light",
          "current_institution_code": "chase",
          "current_institution_guid": "INS-f1a3285d-e855-b61f-6aa7-8ae575c0e0e9",
          "current_member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
          "disable_institution_search": false,
          "include_transactions": true,
          "is_mobile_webview": true,
          "mode": "aggregation",
          "ui_message_version": 4,
          "ui_message_webview_url_scheme": "mx",
          "update_credentials": false,
          "wait_for_full_aggregation": false,
          "widget_type": "connect_widget"
        }
      }'

1
2
3
4
5
6
7
{
  widget_url: {  
    type: 'connect_widget',
    url: 'https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    user_id: 'U-jeff-201709221210'
  }
}

1
2
3
4
5
6
7
#<::MxPlatformRuby::WidgetResponseBody
  @widget_url=#<::MxPlatformRuby::WidgetResponse  
    @type='connect_widget',
    @url='https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    @user_id='U-jeff-201709221210'
  >
>

1
2
3
4
5
6
7
{
  "widget_url": {  
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

Request a Connect URL (deprecated)

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

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

Endpoint:

POST /users/{user_guid}/connect_widget_url

1
2
3
4
5
6
7
8
9
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
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const requestBody = {
  config: {  
    color_scheme: 'light',
    current_institution_code: 'chase',
    current_member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    disable_institution_search: false,
    include_transactions: true,
    is_mobile_webview: true,
    mode: 'aggregation',
    ui_message_version: 4,
    ui_message_webview_url_scheme: 'mx',
    update_credentials: false,
    wait_for_full_aggregation: false
  }
};

const response = await client.requestConnectWidgetURL(userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
request_body = ::MxPlatformRuby::ConnectWidgetRequestBody.new(
  config: ::MxPlatformRuby::ConnectWidgetRequest.new(  
    color_scheme: 'light',
    current_institution_code: 'chase',
    current_member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    disable_institution_search: false,
    include_transactions: true,
    is_mobile_webview: true,
    mode: 'aggregation',
    ui_message_version: 4,
    ui_message_webview_url_scheme: 'mx',
    update_credentials: false,
    wait_for_full_aggregation: false
  )
)

begin
  response = mx_platform_api.request_connect_widget_url(user_guid, request_body)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_connect_widget_url: #{e}"
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl -i -X POST 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/connect_widget_url' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \
  -d '{      
        "config": {        
          "color_scheme": "light",
          "current_institution_code": "chase",
          "current_member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
          "disable_institution_search": false,
          "include_transactions": true,
          "is_mobile_webview": true,
          "mode": "aggregation",
          "ui_message_version": 4,
          "ui_message_webview_url_scheme": "mx",
          "update_credentials": false,
          "wait_for_full_aggregation": false
        }
      }'

1
2
3
4
5
6
{
  user: {  
    connect_widget_url: 'https://int-widgets.moneydesktop.com/md/connect/jb1rA14m85tw2lyvpgfx4gc6d3Z8z8Ayb8',
    guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
  }
}

1
2
3
4
5
6
#<::MxPlatformRuby::ConnectWidgetResponseBody
  @user=#<::MxPlatformRuby::ConnectWidgetResponse  
    @connect_widget_url='https://int-widgets.moneydesktop.com/md/connect/jb1rA14m85tw2lyvpgfx4gc6d3Z8z8Ayb8',
    @guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54'
  >
>

1
2
3
4
5
6
{
  "user": {  
    "connect_widget_url": "https://int-widgets.moneydesktop.com/md/connect/jb1rA14m85tw2lyvpgfx4gc6d3Z8z8Ayb8",
    "guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

Minimum dimensions and breakpoints

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

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

Minimum height: 550px
Minimum width: 320px

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

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

Configuring Connect

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

Language options

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
`es`	connect_widget
`fr`	accounts_widget, connect_widget, pulse_widget, mini_pulse_carousel_widget
`fr-CA`	accounts_widget, connect_widget, pulse_widget, mini_pulse_carousel_widget

Configuration scenarios

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

Excluding transaction data

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53';
const requestBody = {
  widget_url: {
    include_transactions: false,
    widget_type: 'connect_widget'
  }
};

const response = await client.requestWidgetURL(userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53'
opts = {}
request_body = ::MxPlatformRuby::WidgetRequestBody.new(
  widget_url: ::MxPlatformRuby::WidgetRequest.new(
    include_transactions: false,
    widget_type: 'connect_widget'
  )
)

begin
  response = mx_platform_api.request_widget_url(user_guid, request_body, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_widget_url: #{e}"
end

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

1
2
3
4
5
6
7
{
  widget_url: {
    type: 'connect_widget',
    url: 'https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    user_id: 'U-jeff-201709221210'
  }
}

1
2
3
4
5
6
7
#<::MxPlatformRuby::WidgetResponseBody
  @widget_url=#<::MxPlatformRuby::WidgetResponse
    @type='connect_widget',
    @url='https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    @user_id='U-jeff-201709221210'
  >
>

Loading a specific institution

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53';
const requestBody = {
  widget_url: {
    current_institution_code: '{bank code}',
    widget_type: 'connect_widget'
  }
};

const response = await client.requestWidgetURL(userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53'
opts = {}
request_body = ::MxPlatformRuby::WidgetRequestBody.new(
  widget_url: ::MxPlatformRuby::WidgetRequest.new(
    current_institution_code: '{bank code}',
    widget_type: 'connect_widget'
  )
)

begin
  response = mx_platform_api.request_widget_url(user_guid, request_body, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_widget_url: #{e}"
end

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

1
2
3
4
5
6
7
{
  widget_url: {
    type: 'connect_widget',
    url: 'https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    user_id: 'U-jeff-201709221210'
  }
}

1
2
3
4
5
6
7
#<::MxPlatformRuby::WidgetResponseBody
  @widget_url=#<::MxPlatformRuby::WidgetResponse
    @type='connect_widget',
    @url='https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    @user_id='U-jeff-201709221210'
  >
>

Loading a specific member

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53';
const requestBody = {
  widget_url: {
    current_member_guid: '{member_guid}',
    widget_type: 'connect_widget'
  }
};

const response = await client.requestWidgetURL(userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53'
opts = {}
request_body = ::MxPlatformRuby::WidgetRequestBody.new(
  widget_url: ::MxPlatformRuby::WidgetRequest.new(
    current_member_guid: '{member_guid}',
    widget_type: 'connect_widget'
  )
)

begin
  response = mx_platform_api.request_widget_url(user_guid, request_body, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_widget_url: #{e}"
end

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

1
2
3
4
5
6
7
{
  widget_url: {
    type: 'connect_widget',
    url: 'https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    user_id: 'U-jeff-201709221210'
  }
}

1
2
3
4
5
6
7
#<::MxPlatformRuby::WidgetResponseBody
  @widget_url=#<::MxPlatformRuby::WidgetResponse
    @type='connect_widget',
    @url='https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    @user_id='U-jeff-201709221210'
  >
>

Mobile webviews

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

Verification mode

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53';
const requestBody = {
  widget_url: {
    mode: 'verification',
    widget_type: 'connect_widget'
  }
};

const response = await client.requestWidgetURL(userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53'
opts = {}
request_body = ::MxPlatformRuby::WidgetRequestBody.new(
  widget_url: ::MxPlatformRuby::WidgetRequest.new(
    mode: 'verification',
    widget_type: 'connect_widget'
  )
)

begin
  response = mx_platform_api.request_widget_url(user_guid, request_body, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_widget_url: #{e}"
end

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

1
2
3
4
5
6
7
{
  widget_url: {
    type: 'connect_widget',
    url: 'https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    user_id: 'U-jeff-201709221210'
  }
}

1
2
3
4
5
6
7
#<::MxPlatformRuby::WidgetResponseBody
  @widget_url=#<::MxPlatformRuby::WidgetResponse
    @type='connect_widget',
    @url='https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    @user_id='U-jeff-201709221210'
  >
>

Waiting for a full aggregation

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53';
const requestBody = {
  widget_url: {
    wait_for_full_aggregation: true,
    widget_type: 'connect_widget'
  }
};

const response = await client.requestWidgetURL(userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53'
opts = {}
request_body = ::MxPlatformRuby::WidgetRequestBody.new(
  widget_url: ::MxPlatformRuby::WidgetRequest.new(
    wait_for_full_aggregation: true,
    widget_type: 'connect_widget'
  )
)

begin
  response = mx_platform_api.request_widget_url(user_guid, request_body, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_widget_url: #{e}"
end

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

1
2
3
4
5
6
7
{
  widget_url: {
    type: 'connect_widget',
    url: 'https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    user_id: 'U-jeff-201709221210'
  }
}

1
2
3
4
5
6
7
#<::MxPlatformRuby::WidgetResponseBody
  @widget_url=#<::MxPlatformRuby::WidgetResponse
    @type='connect_widget',
    @url='https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    @user_id='U-jeff-201709221210'
  >
>

Connect Javascript Loader

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

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

Parameters available for the JavaScript loader

Parameter	Data Type	Description	Required?
`config`	Object	This object allows you to set additional parameters to load the MX Connect widget in a specific state.	No
`height`	String	Desired height of the iframe. Defaults to 600 pixels.	No
`id`	String	The `id` of the DOM element you’ll load the widget into.	Yes
`onEvent`	Function	A general event handler. Only available with `ui_message_version: 4` or higher, which is the required version for the MX Platform API.	No
`width`	String	Desired width of the iframe. Defaults to 100% of the parent.	No
`url`	String	A URL for the widget provided as a response to the `POST` request above.	Yes

Example usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<script src="https://atrium.mx.com/connect.js"></script>
/**
 * The reference to "atrium" is a holdover from a legacy API.
 * Nevertheless, this is still the correct source for the widget loader
 * even in the context of the Platform API.
 */

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

Embedding in WebViews

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

ui_message_webview_url_scheme will be mx:// by default.

Example navigation event schema

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

Suggested base configuration for WebViews

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "widget_type": "connect_widget",
          "is_mobile_webview": true,
          "ui_message_version": 4,
          "ui_message_webview_url_scheme": "{app_scheme}"
        }
      }'

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

1
2
3
4
5
6
7
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
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53';
const requestBody = {
  widget_url: {
    is_mobile_webview: true,
    ui_message_version: 4,
    ui_message_webview_url_scheme: '{app_scheme}',
    widget_type: 'connect_widget'
  }
};

const response = await client.requestWidgetURL(userGuid, requestBody);

console.log(response.data);

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

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

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53'
opts = {}
request_body = ::MxPlatformRuby::WidgetRequestBody.new(
  widget_url: ::MxPlatformRuby::WidgetRequest.new(
    is_mobile_webview: true,
    ui_message_version: 4,
    ui_message_webview_url_scheme: '{app_scheme}',
    widget_type: 'connect_widget'
  )
)

begin
  response = mx_platform_api.request_widget_url(user_guid, request_body, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_widget_url: #{e}"
end

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

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

1
2
3
4
5
6
7
{
  widget_url: {
    type: 'connect_widget',
    url: 'https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    user_id: 'U-jeff-201709221210'
  }
}

1
2
3
4
5
6
7
#<::MxPlatformRuby::WidgetResponseBody
  @widget_url=#<::MxPlatformRuby::WidgetResponse
    @type='connect_widget',
    @url='https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    @user_id='U-jeff-201709221210'
  >
>

Code Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public class MainActivity extends AppCompatActivity {
    private WebView webView = null;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
      webView = (WebView) findViewById(R.id.webview);
      webView.setWebViewClient(new ConnectWebviewClient());
      webView.getSettings().setDomStorageEnabled(true);
      webView.getSettings().setJavaScriptEnabled(true);
    }
    private class ConnectWebviewClient extends WebViewClient {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
            if (url.startsWith("mx://")) {
                return true;
            }
            return false;
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class ViewController: UIViewController, WKUIDelegate {
  override func viewDidLoad() {
      super.viewDidLoad()
      webView.delegate = self
      ...
  }

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

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

      // Cancel request
      decisionHandler(.cancel)
      return
    }

    // Allow request
    decisionHandler(.allow)
  }
}

Dealing with OAuth in WebViews

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

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

In-depth configuration documentation can be found here.

In-depth documentation on postMessages can be found here.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53';
const requestBody = {
  widget_url: {
    is_mobile_webview: true,
    ui_message_version: 4,
    ui_message_webview_url_scheme: '{app_scheme}',
    widget_type: 'connect_widget'
  }
};

const response = await client.requestWidgetURL(userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-29eab3cf-6a87-fe97-6279-563b63e75a53'
opts = {}
request_body = ::MxPlatformRuby::WidgetRequestBody.new(
  widget_url: ::MxPlatformRuby::WidgetRequest.new(
    is_mobile_webview: true,
    ui_message_version: 4,
    ui_message_webview_url_scheme: '{app_scheme}',
    widget_type: 'connect_widget'
  )
)

begin
  response = mx_platform_api.request_widget_url(user_guid, request_body, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_widget_url: #{e}"
end

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "U-jeff-201709221210"
  }
}

1
2
3
4
5
6
7
{
  widget_url: {
    type: 'connect_widget',
    url: 'https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    user_id: 'U-jeff-201709221210'
  }
}

1
2
3
4
5
6
7
#<::MxPlatformRuby::WidgetResponseBody
  @widget_url=#<::MxPlatformRuby::WidgetResponse
    @type='connect_widget',
    @url='https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5',
    @user_id='U-jeff-201709221210'
  >
>

Redirecting the user

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

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

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

Redirecting the user

Example redirect with Java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
/**
 * This Client will capture urls from MX and cancel them. It will specifically
 * handle the oauthRequested URL. You will want to set this client as your
 * WebView's client or add this functionality to your own.
 */
public class MXWebViewClient extends WebViewClient {
    private Activity activity;

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

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

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

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

        return false;
    }
}

Example redirect with Swift

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
/**
 * Set up the WebView to capture URLs. You will want to cancel all urls from MX.
 */
class ViewController: UIViewController, WKNavigationDelegate {

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

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

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

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

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

            // Cancel request
            decisionHandler(.cancel)
            return
        }

        // Allow request
        decisionHandler(.allow)
    }

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

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

Getting back to your app

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

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

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

Postmessage events

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

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

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

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

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

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

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

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

Example integration

1
2
3
4
5
6
7
function handleEvent(event) {
  if (event.data.mx) {
    // handle the mx post message using event.data.type and event.data.metadata.
  }
}

window.addEventListener('message', handleEvent)

Example event

1
2
3
4
5
6
7
8
9
const mxEvent = {
  mx: true,
  type: 'mx/account/created',
  metadata: {
    user_guid: 'USR-123',
    session_guid: 'ANS-123'
    // relevant data for the given type
  }
}

Connect loaded

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

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

Connect loaded

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/loaded",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "initial_step": "search"
  }
}

Enter credentials

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

Enter credentials

1
2
3
4
5
6
7
8
9
10
11
12
{
  "type": "mx/connect/enterCredentials",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution": {
      "code": "mxbank",
      "guid": "INS-123"
    }
  }
}

Institution search

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

Institution search

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/institutionSearch",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "query": "MX Bank"
  }
}

Institution selected

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

Institution selected

1
2
3
4
5
6
7
8
9
10
11
12
{
  "type": "mx/connect/selectedInstitution",
  "mx": true,
  "metadata": {
    "code": "mxbank",
    "guid": "INS-123",
    "name": "MX Bank",
    "session_guid": "ANS-123",
    "url": "www.example.com",
    "user_guid": "USR-123"
  }
}

Member connected

Triggered when a member has successfully connected the account.

Member connected

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/memberConnected",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Member connected, primary action selected

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

Member connected

1
2
3
4
5
6
7
8
{
  "type": "mx/connect/connected/primaryAction",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

Member deleted

Triggered when a member has been deleted in the widget.

Member deleted

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/memberDeleted",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Member create error

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

Member create error

1
2
3
4
5
6
7
8
9
10
{
  "type": "mx/connect/createMemberError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution_guid": "INS-123",
    "institution_code": "mxbank"
  }
}

Member status update

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

Member status update

1
2
3
4
5
6
7
8
9
10
{
  "type": "mx/connect/memberStatusUpdate",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123",
    "connection_status": 6
  }
}

OAuth error

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

OAuth error

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/oauthError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

OAuth requested

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

OAuth requested:

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/oauthRequested",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "url": "https://something.com"
  }
}

Step change

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

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

Connect step change

1
2
3
4
5
6
7
8
9
10
{
  "type": "mx/connect/stepChange",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "previous": "search",
    "current": "enterCreds"
  }
}

Submit MFA

Triggered when a user submits an MFA answer.

Submit MFA

1
2
3
4
5
6
7
8
9
{
  "type": "mx/connect/submitMFA",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

Update credentials

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

Update credentials

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "type": "mx/connect/updateCredentials",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123",
    "institution": {
      "code": "mxbank",
      "guid": "INS-123"
    }
  }
}

Widget load

Triggered when the app is loaded.

Widget load event

1
2
3
4
{
  "type": "mx/load",
  "mx": true
}

Widget ping

Used to keep the widget session alive.

Widget ping event

1
2
3
4
5
6
7
8
{
  "type": "mx/ping",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

Accounts

An account represents a financial account held by a financial institution, e.g., a user’s checking or savings account. An account belongs to a member, which represents the user’s overall relationship with a particular financial institution. A checking account may be just one part of a larger relationship that could also include a car loan and a savings account.

Account fields

Field	Data type	Description
`account_number`	String	The account number associated with the `account`. This will typically be a masked or partial account number.
`apr`	Decimal	The annual percentage rate associated with the `account`.
`apy`	Decimal	The annual percentage yield associated with the `account`.
`available_balance`	Decimal	The balance that is available for use in asset accounts like checking and savings. `PENDING` transactions are typically taken into account with the available balance, but this may not always be the case. `available_balance` will usually be a positive value for all account types, determined in the same way as the `balance` field.
`available_credit`	Decimal	The amount of credit available for use in liability accounts like credit cards and lines of credit. `PENDING` transactions are typically taken into account with available credit, but this may not always be the case. `available_credit` will usually be a positive value for all account types, determined in the same way as the `balance` field.
`balance`	Decimal	The current balance of the account. `PENDING` transactions are typically not taken into account with the current balance, but this may not always be the case. This is the value used for the account balance displayed in MX UIs. The balance will usually be a positive value for all account types. Asset-type accounts (`CHECKING`, `SAVINGS`, `INVESTMENT`) may have a negative balance if they are in overdraft. Debt-type accounts (`CREDIT_CARD`, `LOAN`, `LINE_OF_CREDIT`, `MORTGAGE`) may have a negative balance if they are overpaid.
`cash_balance`	Decimal	The cash balance of the `account`.
`cash_surrender_value`	Decimal	The sum of money paid to the policyholder or annuity holder in the event the policy is voluntarily terminated before it matures, or the insured event occurs.
`created_at`	String	The date and time at which the `account` was created on the MX Platform.
`credit_limit`	Decimal	The credit limit associated with the `account`.
`currency_code`	String	The three-character ISO 4217 currency code.
`day_payment_is_due`	Integer	The day of the month the payment is due. For example, the 14th is passed as 14.
`death_benefit`	Integer	The amount paid to the beneficiary of the account upon death of the account owner.
`guid`	String	The unique identifier for the `account`. Defined by MX.
`holdings_value`	Decimal	The value of the holdings associated with the account.
`id`	String	The unique partner-defined identifier for the `account`
`imported_at`	String	The date and time at which the `account` was last successfully aggregated and received data.
`institution_code`	String	A unique identifier for the `institution` associated with this `account`. Defined by MX.
`insured_name`	String	The name of the insured individual.
`interest_rate`	Decimal	The interest rate associated with the `account`.
`is_closed`	Boolean	This indicates whether an account has been closed.
`is_hidden`	Boolean	This indicates whether the account is hidden. Defaults to `false`.
`last_payment_at`	String	The date and time of the most recent payment on the `account`.
`last_payment`	Decimal	The amount of the most recent payment on the `account`.
`loan_amount`	Decimal	The amount of the loan associated with the `account`.
`matures_on`	String	The date on which the `account` matures.
`member_guid`	String	The unique identifier for the `member` associated with the `account`. Defined by MX.
`member_id`	String	The unique, partner-defined, identifier for the `member` associated with this `account`.
`member_is_managed_by_user`	Boolean	This indicates whether the associated `member` is managed by the user or the MX partner. Members created with the managed member feature will have this field set to false.
`metadata`	String	Additional information a partner can store on the `account`.
`minimum_balance`	Decimal	The minimum balance associated with the `account`.
`minimum_payment`	Decimal	The minimum payment required for an account. This can apply to any debt account.
`name`	String	The human-readable name for the `account`.
`nickname`	String	An alternate name for the `account`.
`original_balance`	Decimal	The original balance associated with the `account`. This will always be positive.
`pay_out_amount`	Decimal	The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy.
`payment_due_at`	String	The date and time at which the next payment is due on the `account`.
`payoff_balance`	Decimal	The payoff balance for a debt `account`. This will normally be a positive number.
`premium_amount`	Decimal	The insurance policy’s premium amount.
`routing_number`	String	The routing number for the `account`.
`started_on`	String	The date on which a debt account was started.
`subtype`	String	The account’s subtype, e.g., `PLAN_401_K`, `MONEY_MARKET`, or `HOME_EQUITY`.
`total_account_value`	Decimal	The total value of the account.
`type`	String	The general or parent type of the `account`.
`updated_at`	String	The date and time at which the `account` was most recently updated.
`user_guid`	String	The unique identifier for the `user` associated with the `account`. Defined by MX.
`user_id`	String	The unique, partner-defined, identifier for the `user` associated with this `account`.

Account types and subtypes

Parent types
ANY (not provided by data partner or invalid number provided)
CHECKING
SAVINGS
LOAN
CREDIT_CARD
INVESTMENT
LINE_OF_CREDIT
MORTGAGE
PROPERTY
CASH
INSURANCE
PREPAID

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

List accounts

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

Endpoint:

GET /users/{user_guid}/accounts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const page = 1;
const recordsPerPage = 10;

const response = await client.listUserAccounts(userGuid, page, recordsPerPage);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  page: 1,
  records_per_page: 10
}

begin
  response = mx_platform_api.list_user_accounts(user_guid, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_user_accounts: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/accounts?page=1&records_per_page=10' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
{
  accounts: [
    {    
      account_number: '5366',
      apr: 1.0,
      apy: 1.0,
      available_balance: 1000.0,
      available_credit: 1000.0,
      balance: 1000.0,
      cash_balance: 1000.0,
      cash_surrender_value: 1000.0,
      created_at: '2016-10-13T17:57:37.000Z',
      credit_limit: 100.0,
      currency_code: 'USD',
      day_payment_is_due: 20,
      death_benefit: 1000,
      guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
      holdings_value: 1000.0,
      id: '1040434698',
      imported_at: '2015-10-13T17:57:37.000Z',
      institution_code: 'chase',
      insured_name: 'Frodo Baggins',
      interest_rate: 1.0,
      is_closed: false,
      is_hidden: false,
      last_payment: 100.0,
      last_payment_at: '2015-10-13T17:57:37.000Z',
      loan_amount: 1000.0,
      matures_on: '2015-10-13T17:57:37.000Z',
      member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      member_id: 'member123',
      member_is_managed_by_user: false,
      metadata: 'some metadata',
      minimum_balance: 100.0,
      minimum_payment: 10.0,
      name: 'Test account 2',
      nickname: 'My Checking',
      original_balance: 10.0,
      pay_out_amount: 10.0,
      payment_due_at: '2015-10-13T17:57:37.000Z',
      payoff_balance: 10.0,
      premium_amount: 1.0,
      routing_number: '68899990000000',
      started_on: '2015-10-13T17:57:37.000Z',
      subtype: 'NONE',
      total_account_value: 1.0,
      type: 'SAVINGS',
      updated_at: '2016-10-13T18:08:00.000Z',
      user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      user_id: 'user123'
    }
  ],
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  }
}

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
#<::MxPlatformRuby::AccountsResponseBody
  @accounts=[
    #<::MxPlatformRuby::AccountResponse    
      @account_number='5366',
      @apr=1.0,
      @apy=1.0,
      @available_balance=1000.0,
      @available_credit=1000.0,
      @balance=1000.0,
      @cash_balance=1000.0,
      @cash_surrender_value=1000.0,
      @created_at='2016-10-13T17:57:37.000Z',
      @credit_limit=100.0,
      @currency_code='USD',
      @day_payment_is_due=20,
      @death_benefit=1000,
      @guid='ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
      @holdings_value=1000.0,
      @id='1040434698',
      @imported_at='2015-10-13T17:57:37.000Z',
      @institution_code='chase',
      @insured_name='Frodo Baggins',
      @interest_rate=1.0,
      @is_closed=false,
      @is_hidden=false,
      @last_payment=100.0,
      @last_payment_at='2015-10-13T17:57:37.000Z',
      @loan_amount=1000.0,
      @matures_on='2015-10-13T17:57:37.000Z',
      @member_guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      @member_id='member123',
      @member_is_managed_by_user=false,
      @metadata='some metadata',
      @minimum_balance=100.0,
      @minimum_payment=10.0,
      @name='Test account 2',
      @nickname='My Checking',
      @original_balance=10.0,
      @pay_out_amount=10.0,
      @payment_due_at='2015-10-13T17:57:37.000Z',
      @payoff_balance=10.0,
      @premium_amount=1.0,
      @routing_number='68899990000000',
      @started_on='2015-10-13T17:57:37.000Z',
      @subtype='NONE',
      @total_account_value=1.0,
      @type='SAVINGS',
      @updated_at='2016-10-13T18:08:00.000Z',
      @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      @user_id='user123'
    >
  ],
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >
>

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
{
  "accounts": [
    {    
      "account_number": "5366",
      "apr": 1.0,
      "apy": 1.0,
      "available_balance": 1000.0,
      "available_credit": 1000.0,
      "balance": 1000.0,
      "cash_balance": 1000.0,
      "cash_surrender_value": 1000.0,
      "created_at": "2016-10-13T17:57:37.000Z",
      "credit_limit": 100.0,
      "currency_code": "USD",
      "day_payment_is_due": 20,
      "death_benefit": 1000,
      "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "holdings_value": 1000.0,
      "id": "1040434698",
      "imported_at": "2015-10-13T17:57:37.000Z",
      "institution_code": "chase",
      "insured_name": "Frodo Baggins",
      "interest_rate": 1.0,
      "is_closed": false,
      "is_hidden": false,
      "last_payment": 100.0,
      "last_payment_at": "2015-10-13T17:57:37.000Z",
      "loan_amount": 1000.0,
      "matures_on": "2015-10-13T17:57:37.000Z",
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "member_id": "member123",
      "member_is_managed_by_user": false,
      "metadata": "some metadata",
      "minimum_balance": 100.0,
      "minimum_payment": 10.0,
      "name": "Test account 2",
      "nickname": "My Checking",
      "original_balance": 10.0,
      "pay_out_amount": 10.0,
      "payment_due_at": "2015-10-13T17:57:37.000Z",
      "payoff_balance": 10.0,
      "premium_amount": 1.0,
      "routing_number": "68899990000000",
      "started_on": "2015-10-13T17:57:37.000Z",
      "subtype": "NONE",
      "total_account_value": 1.0,
      "type": "SAVINGS",
      "updated_at": "2016-10-13T18:08:00.000Z",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
      "user_id": "user123"
    }
  ],
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read account

This endpoint returns the specified account resource.

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const accountGuid = 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';

const response = await client.readAccount(accountGuid, userGuid);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

account_guid = 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'

begin
  response = mx_platform_api.read_account(account_guid, user_guid)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->read_account: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/accounts/ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
  account: {  
    account_number: '5366',
    apr: 1.0,
    apy: 1.0,
    available_balance: 1000.0,
    available_credit: 1000.0,
    balance: 1000.0,
    cash_balance: 1000.0,
    cash_surrender_value: 1000.0,
    created_at: '2016-10-13T17:57:37.000Z',
    credit_limit: 100.0,
    currency_code: 'USD',
    day_payment_is_due: 20,
    death_benefit: 1000,
    guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
    holdings_value: 1000.0,
    id: '1040434698',
    imported_at: '2015-10-13T17:57:37.000Z',
    institution_code: 'chase',
    insured_name: 'Frodo Baggins',
    interest_rate: 1.0,
    is_closed: false,
    is_hidden: false,
    last_payment: 100.0,
    last_payment_at: '2015-10-13T17:57:37.000Z',
    loan_amount: 1000.0,
    matures_on: '2015-10-13T17:57:37.000Z',
    member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    member_id: 'member123',
    member_is_managed_by_user: false,
    metadata: 'some metadata',
    minimum_balance: 100.0,
    minimum_payment: 10.0,
    name: 'Test account 2',
    nickname: 'My Checking',
    original_balance: 10.0,
    pay_out_amount: 10.0,
    payment_due_at: '2015-10-13T17:57:37.000Z',
    payoff_balance: 10.0,
    premium_amount: 1.0,
    routing_number: '68899990000000',
    started_on: '2015-10-13T17:57:37.000Z',
    subtype: 'NONE',
    total_account_value: 1.0,
    type: 'SAVINGS',
    updated_at: '2016-10-13T18:08:00.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

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
#<::MxPlatformRuby::AccountResponseBody
  @account=#<::MxPlatformRuby::AccountResponse  
    @account_number='5366',
    @apr=1.0,
    @apy=1.0,
    @available_balance=1000.0,
    @available_credit=1000.0,
    @balance=1000.0,
    @cash_balance=1000.0,
    @cash_surrender_value=1000.0,
    @created_at='2016-10-13T17:57:37.000Z',
    @credit_limit=100.0,
    @currency_code='USD',
    @day_payment_is_due=20,
    @death_benefit=1000,
    @guid='ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
    @holdings_value=1000.0,
    @id='1040434698',
    @imported_at='2015-10-13T17:57:37.000Z',
    @institution_code='chase',
    @insured_name='Frodo Baggins',
    @interest_rate=1.0,
    @is_closed=false,
    @is_hidden=false,
    @last_payment=100.0,
    @last_payment_at='2015-10-13T17:57:37.000Z',
    @loan_amount=1000.0,
    @matures_on='2015-10-13T17:57:37.000Z',
    @member_guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @member_id='member123',
    @member_is_managed_by_user=false,
    @metadata='some metadata',
    @minimum_balance=100.0,
    @minimum_payment=10.0,
    @name='Test account 2',
    @nickname='My Checking',
    @original_balance=10.0,
    @pay_out_amount=10.0,
    @payment_due_at='2015-10-13T17:57:37.000Z',
    @payoff_balance=10.0,
    @premium_amount=1.0,
    @routing_number='68899990000000',
    @started_on='2015-10-13T17:57:37.000Z',
    @subtype='NONE',
    @total_account_value=1.0,
    @type='SAVINGS',
    @updated_at='2016-10-13T18:08:00.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
  "account": {  
    "account_number": "5366",
    "apr": 1.0,
    "apy": 1.0,
    "available_balance": 1000.0,
    "available_credit": 1000.0,
    "balance": 1000.0,
    "cash_balance": 1000.0,
    "cash_surrender_value": 1000.0,
    "created_at": "2016-10-13T17:57:37.000Z",
    "credit_limit": 100.0,
    "currency_code": "USD",
    "day_payment_is_due": 20,
    "death_benefit": 1000,
    "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "holdings_value": 1000.0,
    "id": "1040434698",
    "imported_at": "2015-10-13T17:57:37.000Z",
    "institution_code": "chase",
    "insured_name": "Frodo Baggins",
    "interest_rate": 1.0,
    "is_closed": false,
    "is_hidden": false,
    "last_payment": 100.0,
    "last_payment_at": "2015-10-13T17:57:37.000Z",
    "loan_amount": 1000.0,
    "matures_on": "2015-10-13T17:57:37.000Z",
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "member_id": "member123",
    "member_is_managed_by_user": false,
    "metadata": "some metadata",
    "minimum_balance": 100.0,
    "minimum_payment": 10.0,
    "name": "Test account 2",
    "nickname": "My Checking",
    "original_balance": 10.0,
    "pay_out_amount": 10.0,
    "payment_due_at": "2015-10-13T17:57:37.000Z",
    "payoff_balance": 10.0,
    "premium_amount": 1.0,
    "routing_number": "68899990000000",
    "started_on": "2015-10-13T17:57:37.000Z",
    "subtype": "NONE",
    "total_account_value": 1.0,
    "type": "SAVINGS",
    "updated_at": "2016-10-13T18:08:00.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Update account

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

Parameters

Field name	Data type	Required?
`is_hidden`	Boolean	No

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const accountGuid = 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1';
const requestBody = {
  account: {  
    is_hidden: false
  }
};

const response = await client.updateAccountByMember(userGuid, memberGuid, accountGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
account_guid = 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1'
request_body = ::MxPlatformRuby::AccountUpdateRequestBody.new(
  account: ::MxPlatformRuby::AccountUpdateRequest.new(  
    is_hidden: false
  )
)

begin
  response = mx_platform_api.update_account_by_member(user_guid, member_guid, account_guid, request_body)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->update_account_by_member: #{e}"
end

1
2
3
4
5
6
7
8
9
curl -i -X PUT 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/accounts/ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \
  -d '{      
        "account": {        
          "is_hidden": false
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
  account: {  
    account_number: '5366',
    apr: 1.0,
    apy: 1.0,
    available_balance: 1000.0,
    available_credit: 1000.0,
    balance: 1000.0,
    cash_balance: 1000.0,
    cash_surrender_value: 1000.0,
    created_at: '2016-10-13T17:57:37.000Z',
    credit_limit: 100.0,
    currency_code: 'USD',
    day_payment_is_due: 20,
    death_benefit: 1000,
    guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
    holdings_value: 1000.0,
    id: '1040434698',
    imported_at: '2015-10-13T17:57:37.000Z',
    institution_code: 'chase',
    insured_name: 'Frodo Baggins',
    interest_rate: 1.0,
    is_closed: false,
    is_hidden: false,
    last_payment: 100.0,
    last_payment_at: '2015-10-13T17:57:37.000Z',
    loan_amount: 1000.0,
    matures_on: '2015-10-13T17:57:37.000Z',
    member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    member_id: 'member123',
    member_is_managed_by_user: false,
    metadata: 'some metadata',
    minimum_balance: 100.0,
    minimum_payment: 10.0,
    name: 'Test account 2',
    nickname: 'My Checking',
    original_balance: 10.0,
    pay_out_amount: 10.0,
    payment_due_at: '2015-10-13T17:57:37.000Z',
    payoff_balance: 10.0,
    premium_amount: 1.0,
    routing_number: '68899990000000',
    started_on: '2015-10-13T17:57:37.000Z',
    subtype: 'NONE',
    total_account_value: 1.0,
    type: 'SAVINGS',
    updated_at: '2016-10-13T18:08:00.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

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
#<::MxPlatformRuby::AccountResponseBody
  @account=#<::MxPlatformRuby::AccountResponse  
    @account_number='5366',
    @apr=1.0,
    @apy=1.0,
    @available_balance=1000.0,
    @available_credit=1000.0,
    @balance=1000.0,
    @cash_balance=1000.0,
    @cash_surrender_value=1000.0,
    @created_at='2016-10-13T17:57:37.000Z',
    @credit_limit=100.0,
    @currency_code='USD',
    @day_payment_is_due=20,
    @death_benefit=1000,
    @guid='ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
    @holdings_value=1000.0,
    @id='1040434698',
    @imported_at='2015-10-13T17:57:37.000Z',
    @institution_code='chase',
    @insured_name='Frodo Baggins',
    @interest_rate=1.0,
    @is_closed=false,
    @is_hidden=false,
    @last_payment=100.0,
    @last_payment_at='2015-10-13T17:57:37.000Z',
    @loan_amount=1000.0,
    @matures_on='2015-10-13T17:57:37.000Z',
    @member_guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @member_id='member123',
    @member_is_managed_by_user=false,
    @metadata='some metadata',
    @minimum_balance=100.0,
    @minimum_payment=10.0,
    @name='Test account 2',
    @nickname='My Checking',
    @original_balance=10.0,
    @pay_out_amount=10.0,
    @payment_due_at='2015-10-13T17:57:37.000Z',
    @payoff_balance=10.0,
    @premium_amount=1.0,
    @routing_number='68899990000000',
    @started_on='2015-10-13T17:57:37.000Z',
    @subtype='NONE',
    @total_account_value=1.0,
    @type='SAVINGS',
    @updated_at='2016-10-13T18:08:00.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
  "account": {  
    "account_number": "5366",
    "apr": 1.0,
    "apy": 1.0,
    "available_balance": 1000.0,
    "available_credit": 1000.0,
    "balance": 1000.0,
    "cash_balance": 1000.0,
    "cash_surrender_value": 1000.0,
    "created_at": "2016-10-13T17:57:37.000Z",
    "credit_limit": 100.0,
    "currency_code": "USD",
    "day_payment_is_due": 20,
    "death_benefit": 1000,
    "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "holdings_value": 1000.0,
    "id": "1040434698",
    "imported_at": "2015-10-13T17:57:37.000Z",
    "institution_code": "chase",
    "insured_name": "Frodo Baggins",
    "interest_rate": 1.0,
    "is_closed": false,
    "is_hidden": false,
    "last_payment": 100.0,
    "last_payment_at": "2015-10-13T17:57:37.000Z",
    "loan_amount": 1000.0,
    "matures_on": "2015-10-13T17:57:37.000Z",
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "member_id": "member123",
    "member_is_managed_by_user": false,
    "metadata": "some metadata",
    "minimum_balance": 100.0,
    "minimum_payment": 10.0,
    "name": "Test account 2",
    "nickname": "My Checking",
    "original_balance": 10.0,
    "pay_out_amount": 10.0,
    "payment_due_at": "2015-10-13T17:57:37.000Z",
    "payoff_balance": 10.0,
    "premium_amount": 1.0,
    "routing_number": "68899990000000",
    "started_on": "2015-10-13T17:57:37.000Z",
    "subtype": "NONE",
    "total_account_value": 1.0,
    "type": "SAVINGS",
    "updated_at": "2016-10-13T18:08:00.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Institutions

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

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

In the integration environment, only some of the top financial institutions will be included in institution endpoints, and there is only one institution that supports OAuth: mx_bank_oauth.

In the production environment, all institutions will be included in these endpoints. However, if you have not yet been registered with institutions that support OAuth, these will be excluded until registration is approved.

Institution fields

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

List favorites

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

Please contact MX to set a list of favorites.

Endpoint:

GET /institutions/favorites

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const page = 1;
const recordsPerPage = 10;

const response = await client.listFavoriteInstitutions(page, recordsPerPage);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

opts = {
  page: 1,
  records_per_page: 10
}

begin
  response = mx_platform_api.list_favorite_institutions(opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_favorite_institutions: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/institutions/favorites?page=1&records_per_page=10' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  institutions: [
    {    
      code: 'chase',
      medium_logo_url: 'https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png',
      name: 'Chase Bank',
      small_logo_url: 'https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png',
      supports_account_identification: true,
      supports_account_statement: true,
      supports_account_verification: true,
      supports_oauth: true,
      supports_transaction_history: true,
      url: 'https://www.chase.com'
    }
  ],
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
#<::MxPlatformRuby::InstitutionsResponseBody
  @institutions=[
    #<::MxPlatformRuby::InstitutionResponse    
      @code='chase',
      @medium_logo_url='https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png',
      @name='Chase Bank',
      @small_logo_url='https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png',
      @supports_account_identification=true,
      @supports_account_statement=true,
      @supports_account_verification=true,
      @supports_oauth=true,
      @supports_transaction_history=true,
      @url='https://www.chase.com'
    >
  ],
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "institutions": [
    {    
      "code": "chase",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "Chase Bank",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": true,
      "supports_account_statement": true,
      "supports_account_verification": true,
      "supports_oauth": true,
      "supports_transaction_history": true,
      "url": "https://www.chase.com"
    }
  ],
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List institution-required credentials

Endpoint:

GET /institutions/{institution_code}/credentials

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const institutionCode = 'chase';
const page = 1;
const recordsPerPage = 10;

const response = await client.listInstitutionCredentials(institutionCode, page, recordsPerPage);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

institution_code = 'chase'
opts = {
  page: 1,
  records_per_page: 10
}

begin
  response = mx_platform_api.list_institution_credentials(institution_code, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_institution_credentials: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/institutions/chase/credentials?page=1&records_per_page=10' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  credentials: [
    {    
      display_order: 1,
      field_name: 'LOGIN',
      field_type: 'TEXT',
      guid: 'CRD-1ec152cd-e628-e81a-e852-d1e7104624da',
      label: 'Username'
    }
  ],
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#<::MxPlatformRuby::CredentialsResponseBody
  @credentials=[
    #<::MxPlatformRuby::CredentialResponse    
      @display_order=1,
      @field_name='LOGIN',
      @field_type='TEXT',
      @guid='CRD-1ec152cd-e628-e81a-e852-d1e7104624da',
      @label='Username'
    >
  ],
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "credentials": [
    {    
      "display_order": 1,
      "field_name": "LOGIN",
      "field_type": "TEXT",
      "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
      "label": "Username"
    }
  ],
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List institutions

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

Query parameters

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

Endpoint:

GET /institutions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const name = 'chase';
const page = 1;
const recordsPerPage = 10;
const supportsAccountIdentification = true;
const supportsAccountStatement = true;
const supportsAccountVerification = true;
const supportsTransactionHistory = true;

const response = await client.listInstitutions(name, page, recordsPerPage, supportsAccountIdentification, supportsAccountStatement, supportsAccountVerification, supportsTransactionHistory);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

opts = {
  name: 'chase',
  page: 1,
  records_per_page: 10,
  supports_account_identification: true,
  supports_account_statement: true,
  supports_account_verification: true,
  supports_transaction_history: true
}

begin
  response = mx_platform_api.list_institutions(opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_institutions: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/institutions?name=chase&page=1&records_per_page=10&supports_account_identification=true&supports_account_statement=true&supports_account_verification=true&supports_transaction_history=true' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  institutions: [
    {    
      code: 'chase',
      medium_logo_url: 'https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png',
      name: 'Chase Bank',
      small_logo_url: 'https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png',
      supports_account_identification: true,
      supports_account_statement: true,
      supports_account_verification: true,
      supports_oauth: true,
      supports_transaction_history: true,
      url: 'https://www.chase.com'
    }
  ],
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
#<::MxPlatformRuby::InstitutionsResponseBody
  @institutions=[
    #<::MxPlatformRuby::InstitutionResponse    
      @code='chase',
      @medium_logo_url='https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png',
      @name='Chase Bank',
      @small_logo_url='https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png',
      @supports_account_identification=true,
      @supports_account_statement=true,
      @supports_account_verification=true,
      @supports_oauth=true,
      @supports_transaction_history=true,
      @url='https://www.chase.com'
    >
  ],
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "institutions": [
    {    
      "code": "chase",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "Chase Bank",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": true,
      "supports_account_statement": true,
      "supports_account_verification": true,
      "supports_oauth": true,
      "supports_transaction_history": true,
      "url": "https://www.chase.com"
    }
  ],
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read institution

This endpoint returns information about the institution specified by institution_code.

Endpoint:

GET /institutions/{institution_code}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const institutionCode = 'chase';

const response = await client.readInstitution(institutionCode);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

institution_code = 'chase'

begin
  response = mx_platform_api.read_institution(institution_code)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->read_institution: #{e}"
end

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  institution: {  
    code: 'chase',
    medium_logo_url: 'https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png',
    name: 'Chase Bank',
    small_logo_url: 'https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png',
    supports_account_identification: true,
    supports_account_statement: true,
    supports_account_verification: true,
    supports_oauth: true,
    supports_transaction_history: true,
    url: 'https://www.chase.com'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#<::MxPlatformRuby::InstitutionResponseBody
  @institution=#<::MxPlatformRuby::InstitutionResponse  
    @code='chase',
    @medium_logo_url='https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png',
    @name='Chase Bank',
    @small_logo_url='https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png',
    @supports_account_identification=true,
    @supports_account_statement=true,
    @supports_account_verification=true,
    @supports_oauth=true,
    @supports_transaction_history=true,
    @url='https://www.chase.com'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "institution": {  
    "code": "chase",
    "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
    "name": "Chase Bank",
    "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
    "supports_account_identification": true,
    "supports_account_statement": true,
    "supports_account_verification": true,
    "supports_oauth": true,
    "supports_transaction_history": true,
    "url": "https://www.chase.com"
  }
}

Members

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

Member fields

Field	Data type	Definition
`aggregated_at`	String	The date and time the most recent aggregation-type job was started, given in ISO 8601 format with a time component. A job will automatically be started when a member is created or its credentials are updated, unless the `skip_aggregation` parameter is used. Jobs can also be started via manual aggregations, background aggregations, API endpoints, or when opening an MX widget. A job can be a normal aggregation, or a premium job such as identification, verification, fetching statements, or fetching an extended transaction history. If a member is deleted and then re-created with the `skip_aggregation` parameter set to true or if it is re-created within the throttle window (typically three hours), the previous value will be returned.
`connection_status`	String	This indicates the state of a member’s aggregation. See member connection statuses for more information.
`guid`	String	The unique identifier for the `member`. Defined by MX.
`id`	String	The partner-defined unique identifier for the `member`.
`institution_code`	String	The unique identifier for the `institution` associated with the `member`. Defined by MX.
`is_being_aggregated`	Boolean	This indicates whether the `member` was being aggregated at the time of the request.
`is_managed_by_user`	String	This indicates whether the member is managed by the user or the MX partner. Members created with the managed member feature will have this field set to false.
`is_oauth`	Boolean	This indicates whether the `member` uses OAuth to authenticate. Defaults to `false`.
`metadata`	String	Additional information you can store on this `member`.
`name`	String	The name of the `member`.
`successfully_aggregated_at`	String	The date and time the member was last successfully aggregated.
`user_guid`	String	The unique identifier for the `user` associated with the `member`. Defined by MX.
`user_id`	String	The unique partner-defined identifier for the `user` associated with the `member`.

Connection statuses

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

Aggregate member

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

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';

const response = await client.aggregateMember(memberGuid, userGuid);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'

begin
  response = mx_platform_api.aggregate_member(member_guid, user_guid)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->aggregate_member: #{e}"
end

1
2
3
4
curl -i -X POST 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/aggregate' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    connection_status: 'CONNECTED',
    guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    id: 'unique_id',
    institution_code: 'chase',
    is_being_aggregated: false,
    is_managed_by_user: false,
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    name: 'Chase Bank',
    oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    successfully_aggregated_at: '2016-10-13T17:57:38.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#<::MxPlatformRuby::MemberResponseBody
  @member=#<::MxPlatformRuby::MemberResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @connection_status='CONNECTED',
    @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @id='unique_id',
    @institution_code='chase',
    @is_being_aggregated=false,
    @is_managed_by_user=false,
    @is_oauth=false,
    @metadata='\"credentials_last_refreshed_at\": \"2015-10-15\"',
    @name='Chase Bank',
    @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    @successfully_aggregated_at='2016-10-13T17:57:38.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "id": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
    "name": "Chase Bank",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Check balances

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

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

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';

const response = await client.checkBalances(memberGuid, userGuid);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'

begin
  response = mx_platform_api.check_balances(member_guid, user_guid)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->check_balances: #{e}"
end

1
2
3
4
curl -i -X POST 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/check_balance' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    connection_status: 'CONNECTED',
    guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    id: 'unique_id',
    institution_code: 'chase',
    is_being_aggregated: false,
    is_managed_by_user: false,
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    name: 'Chase Bank',
    oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    successfully_aggregated_at: '2016-10-13T17:57:38.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#<::MxPlatformRuby::MemberResponseBody
  @member=#<::MxPlatformRuby::MemberResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @connection_status='CONNECTED',
    @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @id='unique_id',
    @institution_code='chase',
    @is_being_aggregated=false,
    @is_managed_by_user=false,
    @is_oauth=false,
    @metadata='\"credentials_last_refreshed_at\": \"2015-10-15\"',
    @name='Chase Bank',
    @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    @successfully_aggregated_at='2016-10-13T17:57:38.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "id": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
    "name": "Chase Bank",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Create member

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

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

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

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

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

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

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

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

Endpoint:

POST /users/{user_guid}/members

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const requestBody = {
  member: {  
    background_aggregation_is_disabled: false,
    credentials: [
      {      
        guid: 'CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f',
        value: 'password'
      }
    ],
    id: 'unique_id',
    institution_code: 'chase',
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    skip_aggregation: false
  },
  referral_source: 'APP',
  ui_message_webview_url_scheme: 'mx'
};

const response = await client.createMember(userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
request_body = ::MxPlatformRuby::MemberCreateRequestBody.new(
  member: ::MxPlatformRuby::MemberCreateRequest.new(  
    background_aggregation_is_disabled: false,
    credentials: [
      ::MxPlatformRuby::CredentialRequest.new(      
        guid: 'CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f',
        value: 'password'
      )
    ],
    id: 'unique_id',
    institution_code: 'chase',
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    skip_aggregation: false
  ),
  referral_source: 'APP',
  ui_message_webview_url_scheme: 'mx'
)

begin
  response = mx_platform_api.create_member(user_guid, request_body)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->create_member: #{e}"
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
curl -i -X POST 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \
  -d '{      
        "member": {        
          "background_aggregation_is_disabled": false,
          "credentials": [
            {            
              "guid": "CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f",
              "value": "password"
            }
          ],
          "id": "unique_id",
          "institution_code": "chase",
          "is_oauth": false,
          "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
          "skip_aggregation": false
        },
        "referral_source": "APP",
        "ui_message_webview_url_scheme": "mx"
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    connection_status: 'CONNECTED',
    guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    id: 'unique_id',
    institution_code: 'chase',
    is_being_aggregated: false,
    is_managed_by_user: false,
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    name: 'Chase Bank',
    oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    successfully_aggregated_at: '2016-10-13T17:57:38.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#<::MxPlatformRuby::MemberResponseBody
  @member=#<::MxPlatformRuby::MemberResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @connection_status='CONNECTED',
    @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @id='unique_id',
    @institution_code='chase',
    @is_being_aggregated=false,
    @is_managed_by_user=false,
    @is_oauth=false,
    @metadata='\"credentials_last_refreshed_at\": \"2015-10-15\"',
    @name='Chase Bank',
    @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    @successfully_aggregated_at='2016-10-13T17:57:38.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "id": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
    "name": "Chase Bank",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Delete member

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

A successful response will have the status 204 No Content.

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';

const response = await client.deleteMember(memberGuid, userGuid);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'

begin
  response = mx_platform_api.delete_member(member_guid, user_guid)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->delete_member: #{e}"
end

1
2
3
curl -i -X DELETE 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

Generate an OAuth window URI

This endpoint will generate an oauth_window_uri for the specified member.

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

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

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

Query parameters

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const referralSource = 'APP';
const uiMessageWebviewUrlScheme = 'mx';
const skipAggregation = false;

const response = await client.requestOAuthWindowURI(memberGuid, userGuid, referralSource, uiMessageWebviewUrlScheme, skipAggregation);

console.log(response.data);

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

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  referral_source: 'APP',
  ui_message_webview_url_scheme: 'mx',
  skip_aggregation: false
}

begin
  response = mx_platform_api.request_o_auth_window_uri(member_guid, user_guid, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->request_o_auth_window_uri: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/oauth_window_uri?referral_source=APP&ui_message_webview_url_scheme=mx&skip_aggregation=false' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
{
  member: {  
    guid: 'MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f',
    oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/zgknnw5k7dmztn2njmwlgz574mZlnft6vdrv7kzn9ptj325th6c5p0w6c7j83Ap1bqg01mhsr1bqjgf2fry3ly9wff497c6fcczbyrfgj7s39cygw95Akl7vlpmcAy2kmvh1mlkytg7jA1z3vnw1w3zx2r1wt65s6f6r3ryqqrysl9qA1kr6cAj6vhr1zl325Azz6hx52j1ll3vwbvvbv5xzy7d6csplyw25brA7147vAfq29ArjjAj4qmc6r6h457hkcj2946m0kjp2xzpkz6hz55lsp3Avmdb8dsq4xzqmzzqk68s6bp5tj9jsskw4wvcb95vm4fwh9w8phgp67hfj2flrtwcy5bxbtk74?skip_aggregation=false'
  }
}

1
2
3
4
5
6
#<::MxPlatformRuby::OAuthWindowResponseBody
  @member=#<::MxPlatformRuby::OAuthWindowResponse  
    @guid='MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f',
    @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/zgknnw5k7dmztn2njmwlgz574mZlnft6vdrv7kzn9ptj325th6c5p0w6c7j83Ap1bqg01mhsr1bqjgf2fry3ly9wff497c6fcczbyrfgj7s39cygw95Akl7vlpmcAy2kmvh1mlkytg7jA1z3vnw1w3zx2r1wt65s6f6r3ryqqrysl9qA1kr6cAj6vhr1zl325Azz6hx52j1ll3vwbvvbv5xzy7d6csplyw25brA7147vAfq29ArjjAj4qmc6r6h457hkcj2946m0kjp2xzpkz6hz55lsp3Avmdb8dsq4xzqmzzqk68s6bp5tj9jsskw4wvcb95vm4fwh9w8phgp67hfj2flrtwcy5bxbtk74?skip_aggregation=false'
  >
>

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

List member challenges

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

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

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

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

Challenge fields

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const page = 1;
const recordsPerPage = 10;

const response = await client.listMemberChallenges(memberGuid, userGuid, page, recordsPerPage);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  page: 1,
  records_per_page: 10
}

begin
  response = mx_platform_api.list_member_challenges(member_guid, user_guid, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_member_challenges: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/challenges?page=1&records_per_page=10' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  challenges: [
    {    
      field_name: 'Who is this guy?',
      guid: 'CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5',
      image_data: 'Who is this guy?',
      image_options: [
        {        
          data_uri: 'data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ...',
          label: 'IMAGE_1',
          value: 'image_data'
        }
      ],
      label: 'Who is this guy?',
      options: [
        {        
          label: 'IMAGE_1',
          value: 'image_data'
        }
      ],
      type: 'IMAGE_DATA'
    }
  ],
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  }
}

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
#<::MxPlatformRuby::ChallengesResponseBody
  @challenges=[
    #<::MxPlatformRuby::ChallengeResponse    
      @field_name='Who is this guy?',
      @guid='CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5',
      @image_data='Who is this guy?',
      @image_options=[
        #<::MxPlatformRuby::ImageOptionResponse        
          @data_uri='data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ...',
          @label='IMAGE_1',
          @value='image_data'
        >
      ],
      @label='Who is this guy?',
      @options=[
        #<::MxPlatformRuby::OptionResponse        
          @label='IMAGE_1',
          @value='image_data'
        >
      ],
      @type='IMAGE_DATA'
    >
  ],
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >
>

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
{
  "challenges": [
    {    
      "field_name": "Who is this guy?",
      "guid": "CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5",
      "image_data": "Who is this guy?",
      "image_options": [
        {        
          "data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ...",
          "label": "IMAGE_1",
          "value": "image_data"
        }
      ],
      "label": "Who is this guy?",
      "options": [
        {        
          "label": "IMAGE_1",
          "value": "image_data"
        }
      ],
      "type": "IMAGE_DATA"
    }
  ],
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List member credentials

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

Credential fields

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

Credential field types

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const page = 1;
const recordsPerPage = 10;

const response = await client.listMemberCredentials(memberGuid, userGuid, page, recordsPerPage);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  page: 1,
  records_per_page: 10
}

begin
  response = mx_platform_api.list_member_credentials(member_guid, user_guid, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_member_credentials: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/credentials?page=1&records_per_page=10' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  credentials: [
    {    
      display_order: 1,
      field_name: 'LOGIN',
      field_type: 'TEXT',
      guid: 'CRD-1ec152cd-e628-e81a-e852-d1e7104624da',
      label: 'Username'
    }
  ],
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#<::MxPlatformRuby::CredentialsResponseBody
  @credentials=[
    #<::MxPlatformRuby::CredentialResponse    
      @display_order=1,
      @field_name='LOGIN',
      @field_type='TEXT',
      @guid='CRD-1ec152cd-e628-e81a-e852-d1e7104624da',
      @label='Username'
    >
  ],
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "credentials": [
    {    
      "display_order": 1,
      "field_name": "LOGIN",
      "field_type": "TEXT",
      "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
      "label": "Username"
    }
  ],
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

List members

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

Endpoint:

GET /users/{user_guid}/members

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const page = 1;
const recordsPerPage = 10;

const response = await client.listMembers(userGuid, page, recordsPerPage);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  page: 1,
  records_per_page: 10
}

begin
  response = mx_platform_api.list_members(user_guid, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_members: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members?page=1&records_per_page=10' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  members: [
    {    
      aggregated_at: '2016-10-13T18:07:57.000Z',
      connection_status: 'CONNECTED',
      guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      id: 'unique_id',
      institution_code: 'chase',
      is_being_aggregated: false,
      is_managed_by_user: false,
      is_oauth: false,
      metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
      name: 'Chase Bank',
      oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
      successfully_aggregated_at: '2016-10-13T17:57:38.000Z',
      user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      user_id: 'user123'
    }
  ],
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  }
}

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
#<::MxPlatformRuby::MembersResponseBody
  @members=[
    #<::MxPlatformRuby::MemberResponse    
      @aggregated_at='2016-10-13T18:07:57.000Z',
      @connection_status='CONNECTED',
      @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      @id='unique_id',
      @institution_code='chase',
      @is_being_aggregated=false,
      @is_managed_by_user=false,
      @is_oauth=false,
      @metadata='\"credentials_last_refreshed_at\": \"2015-10-15\"',
      @name='Chase Bank',
      @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
      @successfully_aggregated_at='2016-10-13T17:57:38.000Z',
      @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      @user_id='user123'
    >
  ],
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >
>

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
{
  "members": [
    {    
      "aggregated_at": "2016-10-13T18:07:57.000Z",
      "connection_status": "CONNECTED",
      "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "id": "unique_id",
      "institution_code": "chase",
      "is_being_aggregated": false,
      "is_managed_by_user": false,
      "is_oauth": false,
      "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
      "name": "Chase Bank",
      "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
      "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
      "user_id": "user123"
    }
  ],
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

Read member

This endpoint returns information about the specified member.

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';

const response = await client.readMember(memberGuid, userGuid);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'

begin
  response = mx_platform_api.read_member(member_guid, user_guid)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->read_member: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    connection_status: 'CONNECTED',
    guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    id: 'unique_id',
    institution_code: 'chase',
    is_being_aggregated: false,
    is_managed_by_user: false,
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    name: 'Chase Bank',
    oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    successfully_aggregated_at: '2016-10-13T17:57:38.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#<::MxPlatformRuby::MemberResponseBody
  @member=#<::MxPlatformRuby::MemberResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @connection_status='CONNECTED',
    @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @id='unique_id',
    @institution_code='chase',
    @is_being_aggregated=false,
    @is_managed_by_user=false,
    @is_oauth=false,
    @metadata='\"credentials_last_refreshed_at\": \"2015-10-15\"',
    @name='Chase Bank',
    @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    @successfully_aggregated_at='2016-10-13T17:57:38.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "id": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
    "name": "Chase Bank",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Read member status

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

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';

const response = await client.readMemberStatus(memberGuid, userGuid);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'

begin
  response = mx_platform_api.read_member_status(member_guid, user_guid)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->read_member_status: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/status' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    challenges: [
      {      
        field_name: 'Who is this guy?',
        guid: 'CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5',
        image_data: 'Who is this guy?',
        image_options: [
          {          
            data_uri: 'data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ...',
            label: 'IMAGE_1',
            value: 'image_data'
          }
        ],
        label: 'Who is this guy?',
        options: [
          {          
            label: 'IMAGE_1',
            value: 'image_data'
          }
        ],
        type: 'IMAGE_DATA'
      }
    ],
    connection_status: 'CONNECTED',
    guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    has_processed_accounts: true,
    has_processed_transactions: false,
    is_authenticated: false,
    is_being_aggregated: false,
    successfully_aggregated_at: '2016-10-13T17:57:38.000Z'
  }
}

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
#<::MxPlatformRuby::MemberStatusResponseBody
  @member=#<::MxPlatformRuby::MemberStatusResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @challenges=[
      #<::MxPlatformRuby::ChallengeResponse      
        @field_name='Who is this guy?',
        @guid='CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5',
        @image_data='Who is this guy?',
        @image_options=[
          #<::MxPlatformRuby::ImageOptionResponse          
            @data_uri='data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ...',
            @label='IMAGE_1',
            @value='image_data'
          >
        ],
        @label='Who is this guy?',
        @options=[
          #<::MxPlatformRuby::OptionResponse          
            @label='IMAGE_1',
            @value='image_data'
          >
        ],
        @type='IMAGE_DATA'
      >
    ],
    @connection_status='CONNECTED',
    @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @has_processed_accounts=true,
    @has_processed_transactions=false,
    @is_authenticated=false,
    @is_being_aggregated=false,
    @successfully_aggregated_at='2016-10-13T17:57:38.000Z'
  >
>

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
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "challenges": [
      {      
        "field_name": "Who is this guy?",
        "guid": "CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5",
        "image_data": "Who is this guy?",
        "image_options": [
          {          
            "data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ...",
            "label": "IMAGE_1",
            "value": "image_data"
          }
        ],
        "label": "Who is this guy?",
        "options": [
          {          
            "label": "IMAGE_1",
            "value": "image_data"
          }
        ],
        "type": "IMAGE_DATA"
      }
    ],
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "has_processed_accounts": true,
    "has_processed_transactions": false,
    "is_authenticated": false,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z"
  }
}

Resume aggregation

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const requestBody = {
  member: {  
    challenges: [
      {      
        guid: 'CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f',
        value: 'password'
      }
    ]
  }
};

const response = await client.resumeAggregation(memberGuid, userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
request_body = ::MxPlatformRuby::MemberResumeRequestBody.new(
  member: ::MxPlatformRuby::MemberResumeRequest.new(  
    challenges: [
      ::MxPlatformRuby::CredentialRequest.new(      
        guid: 'CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f',
        value: 'password'
      )
    ]
  )
)

begin
  response = mx_platform_api.resume_aggregation(member_guid, user_guid, request_body)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->resume_aggregation: #{e}"
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -i -X PUT 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/resume' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \
  -d '{      
        "member": {        
          "challenges": [
            {            
              "guid": "CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f",
              "value": "password"
            }
          ]
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    connection_status: 'CONNECTED',
    guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    id: 'unique_id',
    institution_code: 'chase',
    is_being_aggregated: false,
    is_managed_by_user: false,
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    name: 'Chase Bank',
    oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    successfully_aggregated_at: '2016-10-13T17:57:38.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#<::MxPlatformRuby::MemberResponseBody
  @member=#<::MxPlatformRuby::MemberResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @connection_status='CONNECTED',
    @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @id='unique_id',
    @institution_code='chase',
    @is_being_aggregated=false,
    @is_managed_by_user=false,
    @is_oauth=false,
    @metadata='\"credentials_last_refreshed_at\": \"2015-10-15\"',
    @name='Chase Bank',
    @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    @successfully_aggregated_at='2016-10-13T17:57:38.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "id": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
    "name": "Chase Bank",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Update member

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

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const requestBody = {
  member: {  
    background_aggregation_is_disabled: false,
    credentials: [
      {      
        guid: 'CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f',
        value: 'password'
      }
    ],
    id: 'unique_id',
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    skip_aggregation: false
  }
};

const response = await client.updateMember(memberGuid, userGuid, requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
request_body = ::MxPlatformRuby::MemberUpdateRequestBody.new(
  member: ::MxPlatformRuby::MemberUpdateRequest.new(  
    background_aggregation_is_disabled: false,
    credentials: [
      ::MxPlatformRuby::CredentialRequest.new(      
        guid: 'CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f',
        value: 'password'
      )
    ],
    id: 'unique_id',
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    skip_aggregation: false
  )
)

begin
  response = mx_platform_api.update_member(member_guid, user_guid, request_body)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->update_member: #{e}"
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
curl -i -X PUT 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \
  -d '{      
        "member": {        
          "background_aggregation_is_disabled": false,
          "credentials": [
            {            
              "guid": "CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f",
              "value": "password"
            }
          ],
          "id": "unique_id",
          "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
          "skip_aggregation": false
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  member: {  
    aggregated_at: '2016-10-13T18:07:57.000Z',
    connection_status: 'CONNECTED',
    guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    id: 'unique_id',
    institution_code: 'chase',
    is_being_aggregated: false,
    is_managed_by_user: false,
    is_oauth: false,
    metadata: '\"credentials_last_refreshed_at\": \"2015-10-15\"',
    name: 'Chase Bank',
    oauth_window_uri: 'int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    successfully_aggregated_at: '2016-10-13T17:57:38.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#<::MxPlatformRuby::MemberResponseBody
  @member=#<::MxPlatformRuby::MemberResponse  
    @aggregated_at='2016-10-13T18:07:57.000Z',
    @connection_status='CONNECTED',
    @guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @id='unique_id',
    @institution_code='chase',
    @is_being_aggregated=false,
    @is_managed_by_user=false,
    @is_oauth=false,
    @metadata='\"credentials_last_refreshed_at\": \"2015-10-15\"',
    @name='Chase Bank',
    @oauth_window_uri='int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp',
    @successfully_aggregated_at='2016-10-13T17:57:38.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {  
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "id": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
    "name": "Chase Bank",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false&referral_source=APP&ui_message_webview_url_scheme=myapp",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Transactions

A transaction represents any instance in which money moves into or out of an account. This could be a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, etc. Each transaction belongs to only one account.

Transaction fields

Field	Data type	Description
`account_guid`	String	The unique identifier for the `account` associated with the `transaction`. Defined by MX.
`account_id`	String	The unique partner-defined identifier for the `account` associated with the `transaction`. This can only be set for partner-managed accounts. It should be ignored for user-managed transactions, even in occasional cases where it may return with a value.
`amount`	Decimal	The monetary amount of the `transaction`.
`category`	String	The category of the `transaction`.
`category_guid`	String	The unique identifier for the `category` assigned to the `transaction`.
`check_number_string`	String	The check number for the `transaction`.
`created_at`	String	The date and time the `transaction` was created.
`currency_code`	String	The three-character ISO 4217 currency code, e.g. `USD`.
`date`	String	The date on which the transaction took place. This is the field used when searching for transactions by date. This field is generally the same as `transacted_at`, but uses `posted_at` as a fallback.
`description`	String	A human-readable version of the `original_description` field described below, e.g., “Sam’s Club,” “Johnny’s Tavern.” This is provided by the MX Platform.
`guid`	String	The unique identifier for the `transaction`. Defined by MX.
`id`	String	The unique partner-defined identifier for the `transaction`. This can only be set for partner-managed transactions. It should be ignored for user-managed transactions, even in occasional cases where it may return with a value.
`is_bill_pay`	Boolean	This indicates whether the `transaction` represents a bill pay.
`is_direct_deposit`	Boolean	This indicates whether the `transaction` represents a direct deposit.
`is_expense`	Boolean	This indicates whether the `transaction` represents an expense.
`is_fee`	Boolean	This indicates whether the `transaction` represents a fee.
`is_income`	Boolean	This indicates whether the `transaction` represents income.
`is_international`	Boolean	If the transaction is international as defined by the data provider, this field will be `true`. If the data provider determines it is not international then it will be `false`. It will be `null` if the data provider does not have this information.
`is_overdraft_fee`	Boolean	This indicates whether the `transaction` represents an overdraft fee.
`is_payroll_advance`	Boolean	This indicates whether the `transaction` represents a payroll advance.
`is_recurring`	Boolean	This indicates whether a transaction is a recurring credit or debit.
`is_subscription`	Boolean	This indicates whether the transaction represents a payment for a subscription service such as Netflix or Audible.
`latitude`	Decimal	The latitude of the location where the `transaction` occurred. The number is a signed decimal (e.g. Rio de Janeiro’s latitude is -22.9027800 and Tokyo’s latitude is 35.689488).
`localized_description`	String	A human-readable description of the transaction, provided in a local language.
`localized_memo`	String	Additional descriptive information about the transaction, provided in a local language.
`longitude`	Decimal	The longitude of the location where the `transaction` occurred. The number is a signed decimal (e.g. Rio de Janeiro’s longitude is -43.2075000 and Tokyo’s longitude is 139.691706).
`member_guid`	String	The unique identifier for the `member` associated with the `transaction` Defined by MX.
`member_is_managed_by_user`	Boolean	This indicates whether the associated `member` is managed by the user or the MX partner. Members created with the managed member feature will have this field set to false.
`memo`	String	This field contains additional descriptive information about the `transaction`.
`merchant_category_code`	Integer	The ISO 18245 category code for the transaction.
`merchant_guid`	String	The unique identifier for the `merchant` associated with this transaction. Defined by MX.
`merchant_location_guid`	String	The unique identifier for the `merchant_location` associated with this transaction. Defined by MX.
`original_description`	String	The original description of the transaction as provided by our data feed. See `description` above for more information.
`posted_at`	String	The date and time the transaction was posted to the account.
`status`	String	The status of the transaction. This will be either `POSTED` or `PENDING`.
`top_level_category`	String	The parent category assigned to this transaction’s category.
`transacted_at`	String	The date and time the transaction took place.
`type`	String	The type of transaction. This will be either `CREDIT` or `DEBIT`.
`updated_at`	String	The date and time the transaction was last updated.
`user_guid`	String	The unique identifier for the `user` associated with this `transaction`. Defined by MX.
`user_id`	String	The unique partner-defined identifier for the `user` associated with the `transaction`.

Transaction categories

Categories

* Auto & Transport
  * Auto Insurance
  * Auto Payment
  * Gas
  * Parking
  * Public Transportation
  * Service & Parts
* Bills & Utilities
  * Domain Names
  * Fraud Protection
  * Home Phone
  * Hosting
  * Internet
  * Mobile Phone
  * Television
  * Utilities
* Business Services
  * Advertising
  * Legal
  * Office Supplies
  * Printing
  * Shipping
* Education
  * Books & Supplies
  * Student Loan
  * Tuition
* Entertainment
  * Amusement
  * Arts
  * Movies & DVDs
  * Music
  * Newspapers & Magazines
* Fees & Charges
  * ATM Fee
  * Banking Fee
  * Finance Charge
  * Late Fee
  * Service Fee
  * Trade Commissions
* Financial
  * Financial Advisor
  * Life Insurance
* Food & Dining
  * Alcohol & Bars
  * Coffee Shops
  * Fast Food
  * Groceries
  * Restaurants
* Gifts & Donations
  * Charity
  * Gift
* Health & Fitness
  * Dentist
  * Doctor
  * Eyecare
  * Gym
  * Health Insurance
  * Pharmacy
  * Sports
* Home
  * Furnishings
  * Home Improvement
  * Home Insurance
  * Home Services
  * Home Supplies
  * Lawn & Garden
  * Mortgage & Rent
* Income
  * Bonus
  * Interest Income
  * Paycheck
  * Reimbursement
  * Rental Income
  * Returned Purchase
* Investments
  * Buy
  * Deposit
  * Dividend & Cap Gains
  * Sell
  * Withdrawal
* Kids
  * Allowance
  * Baby Supplies
  * Babysitter & Daycare
  * Child Support
  * Kids Activities
  * Toys
* Personal Care
  * Hair
  * Laundry
  * Spa & Massage
* Pets
  * Pet Food & Supplies
  * Pet Grooming
  * Veterinary
* Shopping
  * Books
  * Clothing
  * Hobbies
  * Sporting Goods
* Taxes
  * Federal Tax
  * Local Tax
  * Property Tax
  * Sales Tax
  * State Tax
* Transfer
  * Credit Card Payment
  * Transfer for Cash Spending
  * Mortgage Payment
* Travel
  * Air Travel
  * Hotel
  * Rental Car & Taxi
  * Vacation
* Uncategorized
  * Cash
  * Check

Merchant category codes

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

List transactions by account

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

Query string parameters

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const accountGuid = 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const fromDate = '2015-09-20';
const page = 1;
const recordsPerPage = 10;
const toDate = '2019-10-20';

const response = await client.listTransactionsByAccount(accountGuid, userGuid, fromDate, page, recordsPerPage, toDate);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

account_guid = 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  from_date: '2015-09-20',
  page: 1,
  records_per_page: 10,
  to_date: '2019-10-20'
}

begin
  response = mx_platform_api.list_transactions_by_account(account_guid, user_guid, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_transactions_by_account: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/accounts/ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1/transactions?from_date=2015-09-20&page=1&records_per_page=10&to_date=2019-10-20' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  },
  transactions: [
    {    
      account_guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
      account_id: 'account123',
      amount: 61.11,
      category: 'Groceries',
      category_guid: 'CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
      check_number_string: '6812',
      created_at: '2016-10-06T09:43:42.000Z',
      currency_code: 'USD',
      date: '2013-09-23T00:00:00.000Z',
      description: 'Whole foods',
      extended_transaction_type: 'partner_transaction_type',
      guid: 'TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
      id: 'transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
      is_bill_pay: false,
      is_direct_deposit: false,
      is_expense: true,
      is_fee: false,
      is_income: false,
      is_international: false,
      is_overdraft_fee: false,
      is_payroll_advance: false,
      is_recurring: false,
      is_subscription: false,
      latitude: -43.2075,
      localized_description: 'This is a localized_description',
      localized_memo: 'This is a localized_memo',
      longitude: 139.691706,
      member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      member_is_managed_by_user: false,
      memo: 'This is a memo',
      merchant_category_code: 5411,
      merchant_guid: 'MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
      merchant_location_guid: 'MCL-00024e59-18b5-4d79-b879-2a7896726fea',
      metadata: 'some metadata',
      original_description: 'WHOLEFDS TSQ 102',
      posted_at: '2016-10-07T06:00:00.000Z',
      status: 'POSTED',
      top_level_category: 'Food & Dining',
      transacted_at: '2016-10-06T13:00:00.000Z',
      type: 'DEBIT',
      updated_at: '2016-10-07T05:49:12.000Z',
      user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      user_id: 'user123'
    }
  ]
}

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
#<::MxPlatformRuby::TransactionsResponseBody
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >,
  @transactions=[
    #<::MxPlatformRuby::TransactionResponse    
      @account_guid='ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
      @account_id='account123',
      @amount=61.11,
      @category='Groceries',
      @category_guid='CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
      @check_number_string='6812',
      @created_at='2016-10-06T09:43:42.000Z',
      @currency_code='USD',
      @date='2013-09-23T00:00:00.000Z',
      @description='Whole foods',
      @extended_transaction_type='partner_transaction_type',
      @guid='TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
      @id='transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
      @is_bill_pay=false,
      @is_direct_deposit=false,
      @is_expense=true,
      @is_fee=false,
      @is_income=false,
      @is_international=false,
      @is_overdraft_fee=false,
      @is_payroll_advance=false,
      @is_recurring=false,
      @is_subscription=false,
      @latitude=-43.2075,
      @localized_description='This is a localized_description',
      @localized_memo='This is a localized_memo',
      @longitude=139.691706,
      @member_guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      @member_is_managed_by_user=false,
      @memo='This is a memo',
      @merchant_category_code=5411,
      @merchant_guid='MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
      @merchant_location_guid='MCL-00024e59-18b5-4d79-b879-2a7896726fea',
      @metadata='some metadata',
      @original_description='WHOLEFDS TSQ 102',
      @posted_at='2016-10-07T06:00:00.000Z',
      @status='POSTED',
      @top_level_category='Food & Dining',
      @transacted_at='2016-10-06T13:00:00.000Z',
      @type='DEBIT',
      @updated_at='2016-10-07T05:49:12.000Z',
      @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      @user_id='user123'
    >
  ]
>

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
{
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  },
  "transactions": [
    {    
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "account_id": "account123",
      "amount": 61.11,
      "category": "Groceries",
      "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
      "check_number_string": "6812",
      "created_at": "2016-10-06T09:43:42.000Z",
      "currency_code": "USD",
      "date": "2013-09-23T00:00:00.000Z",
      "description": "Whole foods",
      "extended_transaction_type": "partner_transaction_type",
      "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
      "id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": false,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": -43.2075,
      "localized_description": "This is a localized_description",
      "localized_memo": "This is a localized_memo",
      "longitude": 139.691706,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "member_is_managed_by_user": false,
      "memo": "This is a memo",
      "merchant_category_code": 5411,
      "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
      "merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
      "metadata": "some metadata",
      "original_description": "WHOLEFDS TSQ 102",
      "posted_at": "2016-10-07T06:00:00.000Z",
      "status": "POSTED",
      "top_level_category": "Food & Dining",
      "transacted_at": "2016-10-06T13:00:00.000Z",
      "type": "DEBIT",
      "updated_at": "2016-10-07T05:49:12.000Z",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
      "user_id": "user123"
    }
  ]
}

List transactions by member

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

Query string parameters

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const memberGuid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const fromDate = '2015-09-20';
const page = 1;
const recordsPerPage = 10;
const toDate = '2019-10-20';

const response = await client.listTransactionsByMember(memberGuid, userGuid, fromDate, page, recordsPerPage, toDate);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

member_guid = 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  from_date: '2015-09-20',
  page: 1,
  records_per_page: 10,
  to_date: '2019-10-20'
}

begin
  response = mx_platform_api.list_transactions_by_member(member_guid, user_guid, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_transactions_by_member: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/transactions?from_date=2015-09-20&page=1&records_per_page=10&to_date=2019-10-20' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  },
  transactions: [
    {    
      account_guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
      account_id: 'account123',
      amount: 61.11,
      category: 'Groceries',
      category_guid: 'CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
      check_number_string: '6812',
      created_at: '2016-10-06T09:43:42.000Z',
      currency_code: 'USD',
      date: '2013-09-23T00:00:00.000Z',
      description: 'Whole foods',
      extended_transaction_type: 'partner_transaction_type',
      guid: 'TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
      id: 'transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
      is_bill_pay: false,
      is_direct_deposit: false,
      is_expense: true,
      is_fee: false,
      is_income: false,
      is_international: false,
      is_overdraft_fee: false,
      is_payroll_advance: false,
      is_recurring: false,
      is_subscription: false,
      latitude: -43.2075,
      localized_description: 'This is a localized_description',
      localized_memo: 'This is a localized_memo',
      longitude: 139.691706,
      member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      member_is_managed_by_user: false,
      memo: 'This is a memo',
      merchant_category_code: 5411,
      merchant_guid: 'MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
      merchant_location_guid: 'MCL-00024e59-18b5-4d79-b879-2a7896726fea',
      metadata: 'some metadata',
      original_description: 'WHOLEFDS TSQ 102',
      posted_at: '2016-10-07T06:00:00.000Z',
      status: 'POSTED',
      top_level_category: 'Food & Dining',
      transacted_at: '2016-10-06T13:00:00.000Z',
      type: 'DEBIT',
      updated_at: '2016-10-07T05:49:12.000Z',
      user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      user_id: 'user123'
    }
  ]
}

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
#<::MxPlatformRuby::TransactionsResponseBody
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >,
  @transactions=[
    #<::MxPlatformRuby::TransactionResponse    
      @account_guid='ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
      @account_id='account123',
      @amount=61.11,
      @category='Groceries',
      @category_guid='CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
      @check_number_string='6812',
      @created_at='2016-10-06T09:43:42.000Z',
      @currency_code='USD',
      @date='2013-09-23T00:00:00.000Z',
      @description='Whole foods',
      @extended_transaction_type='partner_transaction_type',
      @guid='TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
      @id='transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
      @is_bill_pay=false,
      @is_direct_deposit=false,
      @is_expense=true,
      @is_fee=false,
      @is_income=false,
      @is_international=false,
      @is_overdraft_fee=false,
      @is_payroll_advance=false,
      @is_recurring=false,
      @is_subscription=false,
      @latitude=-43.2075,
      @localized_description='This is a localized_description',
      @localized_memo='This is a localized_memo',
      @longitude=139.691706,
      @member_guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      @member_is_managed_by_user=false,
      @memo='This is a memo',
      @merchant_category_code=5411,
      @merchant_guid='MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
      @merchant_location_guid='MCL-00024e59-18b5-4d79-b879-2a7896726fea',
      @metadata='some metadata',
      @original_description='WHOLEFDS TSQ 102',
      @posted_at='2016-10-07T06:00:00.000Z',
      @status='POSTED',
      @top_level_category='Food & Dining',
      @transacted_at='2016-10-06T13:00:00.000Z',
      @type='DEBIT',
      @updated_at='2016-10-07T05:49:12.000Z',
      @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      @user_id='user123'
    >
  ]
>

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
{
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  },
  "transactions": [
    {    
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "account_id": "account123",
      "amount": 61.11,
      "category": "Groceries",
      "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
      "check_number_string": "6812",
      "created_at": "2016-10-06T09:43:42.000Z",
      "currency_code": "USD",
      "date": "2013-09-23T00:00:00.000Z",
      "description": "Whole foods",
      "extended_transaction_type": "partner_transaction_type",
      "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
      "id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": false,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": -43.2075,
      "localized_description": "This is a localized_description",
      "localized_memo": "This is a localized_memo",
      "longitude": 139.691706,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "member_is_managed_by_user": false,
      "memo": "This is a memo",
      "merchant_category_code": 5411,
      "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
      "merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
      "metadata": "some metadata",
      "original_description": "WHOLEFDS TSQ 102",
      "posted_at": "2016-10-07T06:00:00.000Z",
      "status": "POSTED",
      "top_level_category": "Food & Dining",
      "transacted_at": "2016-10-06T13:00:00.000Z",
      "type": "DEBIT",
      "updated_at": "2016-10-07T05:49:12.000Z",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
      "user_id": "user123"
    }
  ]
}

List transactions by user

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

Query string parameters

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

Endpoint:

GET /users/{user_guid}/transactions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const fromDate = '2015-09-20';
const page = 1;
const recordsPerPage = 10;
const toDate = '2019-10-20';

const response = await client.listTransactions(userGuid, fromDate, page, recordsPerPage, toDate);

console.log(response.data);

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

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
opts = {
  from_date: '2015-09-20',
  page: 1,
  records_per_page: 10,
  to_date: '2019-10-20'
}

begin
  response = mx_platform_api.list_transactions(user_guid, opts)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->list_transactions: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/transactions?from_date=2015-09-20&page=1&records_per_page=10&to_date=2019-10-20' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  pagination: {  
    current_page: 1,
    per_page: 25,
    total_entries: 1,
    total_pages: 1
  },
  transactions: [
    {    
      account_guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
      account_id: 'account123',
      amount: 61.11,
      category: 'Groceries',
      category_guid: 'CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
      check_number_string: '6812',
      created_at: '2016-10-06T09:43:42.000Z',
      currency_code: 'USD',
      date: '2013-09-23T00:00:00.000Z',
      description: 'Whole foods',
      extended_transaction_type: 'partner_transaction_type',
      guid: 'TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
      id: 'transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
      is_bill_pay: false,
      is_direct_deposit: false,
      is_expense: true,
      is_fee: false,
      is_income: false,
      is_international: false,
      is_overdraft_fee: false,
      is_payroll_advance: false,
      is_recurring: false,
      is_subscription: false,
      latitude: -43.2075,
      localized_description: 'This is a localized_description',
      localized_memo: 'This is a localized_memo',
      longitude: 139.691706,
      member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      member_is_managed_by_user: false,
      memo: 'This is a memo',
      merchant_category_code: 5411,
      merchant_guid: 'MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
      merchant_location_guid: 'MCL-00024e59-18b5-4d79-b879-2a7896726fea',
      metadata: 'some metadata',
      original_description: 'WHOLEFDS TSQ 102',
      posted_at: '2016-10-07T06:00:00.000Z',
      status: 'POSTED',
      top_level_category: 'Food & Dining',
      transacted_at: '2016-10-06T13:00:00.000Z',
      type: 'DEBIT',
      updated_at: '2016-10-07T05:49:12.000Z',
      user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      user_id: 'user123'
    }
  ]
}

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
#<::MxPlatformRuby::TransactionsResponseBody
  @pagination=#<::MxPlatformRuby::PaginationResponse  
    @current_page=1,
    @per_page=25,
    @total_entries=1,
    @total_pages=1
  >,
  @transactions=[
    #<::MxPlatformRuby::TransactionResponse    
      @account_guid='ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
      @account_id='account123',
      @amount=61.11,
      @category='Groceries',
      @category_guid='CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
      @check_number_string='6812',
      @created_at='2016-10-06T09:43:42.000Z',
      @currency_code='USD',
      @date='2013-09-23T00:00:00.000Z',
      @description='Whole foods',
      @extended_transaction_type='partner_transaction_type',
      @guid='TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
      @id='transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
      @is_bill_pay=false,
      @is_direct_deposit=false,
      @is_expense=true,
      @is_fee=false,
      @is_income=false,
      @is_international=false,
      @is_overdraft_fee=false,
      @is_payroll_advance=false,
      @is_recurring=false,
      @is_subscription=false,
      @latitude=-43.2075,
      @localized_description='This is a localized_description',
      @localized_memo='This is a localized_memo',
      @longitude=139.691706,
      @member_guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
      @member_is_managed_by_user=false,
      @memo='This is a memo',
      @merchant_category_code=5411,
      @merchant_guid='MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
      @merchant_location_guid='MCL-00024e59-18b5-4d79-b879-2a7896726fea',
      @metadata='some metadata',
      @original_description='WHOLEFDS TSQ 102',
      @posted_at='2016-10-07T06:00:00.000Z',
      @status='POSTED',
      @top_level_category='Food & Dining',
      @transacted_at='2016-10-06T13:00:00.000Z',
      @type='DEBIT',
      @updated_at='2016-10-07T05:49:12.000Z',
      @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
      @user_id='user123'
    >
  ]
>

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
{
  "pagination": {  
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  },
  "transactions": [
    {    
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "account_id": "account123",
      "amount": 61.11,
      "category": "Groceries",
      "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
      "check_number_string": "6812",
      "created_at": "2016-10-06T09:43:42.000Z",
      "currency_code": "USD",
      "date": "2013-09-23T00:00:00.000Z",
      "description": "Whole foods",
      "extended_transaction_type": "partner_transaction_type",
      "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
      "id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": false,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": false,
      "is_subscription": false,
      "latitude": -43.2075,
      "localized_description": "This is a localized_description",
      "localized_memo": "This is a localized_memo",
      "longitude": 139.691706,
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "member_is_managed_by_user": false,
      "memo": "This is a memo",
      "merchant_category_code": 5411,
      "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
      "merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
      "metadata": "some metadata",
      "original_description": "WHOLEFDS TSQ 102",
      "posted_at": "2016-10-07T06:00:00.000Z",
      "status": "POSTED",
      "top_level_category": "Food & Dining",
      "transacted_at": "2016-10-06T13:00:00.000Z",
      "type": "DEBIT",
      "updated_at": "2016-10-07T05:49:12.000Z",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
      "user_id": "user123"
    }
  ]
}

Read transaction

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

Endpoint:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const transactionGuid = 'TRN-810828b0-5210-4878-9bd3-f4ce514f90c4';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';

const response = await client.readTransaction(transactionGuid, userGuid);

console.log(response.data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

transaction_guid = 'TRN-810828b0-5210-4878-9bd3-f4ce514f90c4'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'

begin
  response = mx_platform_api.read_transaction(transaction_guid, user_guid)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->read_transaction: #{e}"
end

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/transactions/TRN-810828b0-5210-4878-9bd3-f4ce514f90c4' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
  transaction: {  
    account_guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
    account_id: 'account123',
    amount: 61.11,
    category: 'Groceries',
    category_guid: 'CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
    check_number_string: '6812',
    created_at: '2016-10-06T09:43:42.000Z',
    currency_code: 'USD',
    date: '2013-09-23T00:00:00.000Z',
    description: 'Whole foods',
    extended_transaction_type: 'partner_transaction_type',
    guid: 'TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
    id: 'transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
    is_bill_pay: false,
    is_direct_deposit: false,
    is_expense: true,
    is_fee: false,
    is_income: false,
    is_international: false,
    is_overdraft_fee: false,
    is_payroll_advance: false,
    is_recurring: false,
    is_subscription: false,
    latitude: -43.2075,
    localized_description: 'This is a localized_description',
    localized_memo: 'This is a localized_memo',
    longitude: 139.691706,
    member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    member_is_managed_by_user: false,
    memo: 'This is a memo',
    merchant_category_code: 5411,
    merchant_guid: 'MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
    merchant_location_guid: 'MCL-00024e59-18b5-4d79-b879-2a7896726fea',
    metadata: 'some metadata',
    original_description: 'WHOLEFDS TSQ 102',
    posted_at: '2016-10-07T06:00:00.000Z',
    status: 'POSTED',
    top_level_category: 'Food & Dining',
    transacted_at: '2016-10-06T13:00:00.000Z',
    type: 'DEBIT',
    updated_at: '2016-10-07T05:49:12.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

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
#<::MxPlatformRuby::TransactionResponseBody
  @transaction=#<::MxPlatformRuby::TransactionResponse  
    @account_guid='ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
    @account_id='account123',
    @amount=61.11,
    @category='Groceries',
    @category_guid='CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
    @check_number_string='6812',
    @created_at='2016-10-06T09:43:42.000Z',
    @currency_code='USD',
    @date='2013-09-23T00:00:00.000Z',
    @description='Whole foods',
    @extended_transaction_type='partner_transaction_type',
    @guid='TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
    @id='transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
    @is_bill_pay=false,
    @is_direct_deposit=false,
    @is_expense=true,
    @is_fee=false,
    @is_income=false,
    @is_international=false,
    @is_overdraft_fee=false,
    @is_payroll_advance=false,
    @is_recurring=false,
    @is_subscription=false,
    @latitude=-43.2075,
    @localized_description='This is a localized_description',
    @localized_memo='This is a localized_memo',
    @longitude=139.691706,
    @member_guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @member_is_managed_by_user=false,
    @memo='This is a memo',
    @merchant_category_code=5411,
    @merchant_guid='MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
    @merchant_location_guid='MCL-00024e59-18b5-4d79-b879-2a7896726fea',
    @metadata='some metadata',
    @original_description='WHOLEFDS TSQ 102',
    @posted_at='2016-10-07T06:00:00.000Z',
    @status='POSTED',
    @top_level_category='Food & Dining',
    @transacted_at='2016-10-06T13:00:00.000Z',
    @type='DEBIT',
    @updated_at='2016-10-07T05:49:12.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

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
{
  "transaction": {  
    "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "account_id": "account123",
    "amount": 61.11,
    "category": "Groceries",
    "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
    "check_number_string": "6812",
    "created_at": "2016-10-06T09:43:42.000Z",
    "currency_code": "USD",
    "date": "2013-09-23T00:00:00.000Z",
    "description": "Whole foods",
    "extended_transaction_type": "partner_transaction_type",
    "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
    "id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": true,
    "is_fee": false,
    "is_income": false,
    "is_international": false,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": false,
    "is_subscription": false,
    "latitude": -43.2075,
    "localized_description": "This is a localized_description",
    "localized_memo": "This is a localized_memo",
    "longitude": 139.691706,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "member_is_managed_by_user": false,
    "memo": "This is a memo",
    "merchant_category_code": 5411,
    "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
    "merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
    "metadata": "some metadata",
    "original_description": "WHOLEFDS TSQ 102",
    "posted_at": "2016-10-07T06:00:00.000Z",
    "status": "POSTED",
    "top_level_category": "Food & Dining",
    "transacted_at": "2016-10-06T13:00:00.000Z",
    "type": "DEBIT",
    "updated_at": "2016-10-07T05:49:12.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Update transaction

Use this endpoint to update a transaction according to its unique GUID.

Parameters

Parameter	Required?
`category_guid`	No
`date`	No
`description`	No
`memo`	No

Endpoint:

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

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
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const transactionGuid = 'TRN-810828b0-5210-4878-9bd3-f4ce514f90c4';
const userGuid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54';
const requestBody = {
  transaction: {  
    description: 'new description'
  }
};

const response = await client.updateTransaction(transactionGuid, userGuid, requestBody);

console.log(response.data);

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

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

transaction_guid = 'TRN-810828b0-5210-4878-9bd3-f4ce514f90c4'
user_guid = 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
request_body = ::MxPlatformRuby::TransactionUpdateRequestBody.new(
  transaction: ::MxPlatformRuby::TransactionUpdateRequest.new(  
    description: 'new description'
  )
)

begin
  response = mx_platform_api.update_transaction(transaction_guid, user_guid, request_body)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->update_transaction: #{e}"
end

1
2
3
4
5
6
7
8
9
curl -i -X PUT 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/transactions/TRN-810828b0-5210-4878-9bd3-f4ce514f90c4' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \
  -d '{      
        "transaction": {        
          "description": "new description"
        }
      }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
  transaction: {  
    account_guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
    account_id: 'account123',
    amount: 61.11,
    category: 'Groceries',
    category_guid: 'CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
    check_number_string: '6812',
    created_at: '2016-10-06T09:43:42.000Z',
    currency_code: 'USD',
    date: '2013-09-23T00:00:00.000Z',
    description: 'Whole foods',
    extended_transaction_type: 'partner_transaction_type',
    guid: 'TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
    id: 'transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
    is_bill_pay: false,
    is_direct_deposit: false,
    is_expense: true,
    is_fee: false,
    is_income: false,
    is_international: false,
    is_overdraft_fee: false,
    is_payroll_advance: false,
    is_recurring: false,
    is_subscription: false,
    latitude: -43.2075,
    localized_description: 'This is a localized_description',
    localized_memo: 'This is a localized_memo',
    longitude: 139.691706,
    member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    member_is_managed_by_user: false,
    memo: 'This is a memo',
    merchant_category_code: 5411,
    merchant_guid: 'MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
    merchant_location_guid: 'MCL-00024e59-18b5-4d79-b879-2a7896726fea',
    metadata: 'some metadata',
    original_description: 'WHOLEFDS TSQ 102',
    posted_at: '2016-10-07T06:00:00.000Z',
    status: 'POSTED',
    top_level_category: 'Food & Dining',
    transacted_at: '2016-10-06T13:00:00.000Z',
    type: 'DEBIT',
    updated_at: '2016-10-07T05:49:12.000Z',
    user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    user_id: 'user123'
  }
}

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
#<::MxPlatformRuby::TransactionResponseBody
  @transaction=#<::MxPlatformRuby::TransactionResponse  
    @account_guid='ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
    @account_id='account123',
    @amount=61.11,
    @category='Groceries',
    @category_guid='CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8',
    @check_number_string='6812',
    @created_at='2016-10-06T09:43:42.000Z',
    @currency_code='USD',
    @date='2013-09-23T00:00:00.000Z',
    @description='Whole foods',
    @extended_transaction_type='partner_transaction_type',
    @guid='TRN-265abee9-889b-af6a-c69b-25157db2bdd9',
    @id='transaction-265abee9-889b-af6a-c69b-25157db2bdd9',
    @is_bill_pay=false,
    @is_direct_deposit=false,
    @is_expense=true,
    @is_fee=false,
    @is_income=false,
    @is_international=false,
    @is_overdraft_fee=false,
    @is_payroll_advance=false,
    @is_recurring=false,
    @is_subscription=false,
    @latitude=-43.2075,
    @localized_description='This is a localized_description',
    @localized_memo='This is a localized_memo',
    @longitude=139.691706,
    @member_guid='MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
    @member_is_managed_by_user=false,
    @memo='This is a memo',
    @merchant_category_code=5411,
    @merchant_guid='MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b',
    @merchant_location_guid='MCL-00024e59-18b5-4d79-b879-2a7896726fea',
    @metadata='some metadata',
    @original_description='WHOLEFDS TSQ 102',
    @posted_at='2016-10-07T06:00:00.000Z',
    @status='POSTED',
    @top_level_category='Food & Dining',
    @transacted_at='2016-10-06T13:00:00.000Z',
    @type='DEBIT',
    @updated_at='2016-10-07T05:49:12.000Z',
    @user_guid='USR-fa7537f3-48aa-a683-a02a-b18940482f54',
    @user_id='user123'
  >
>

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
{
  "transaction": {  
    "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "account_id": "account123",
    "amount": 61.11,
    "category": "Groceries",
    "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
    "check_number_string": "6812",
    "created_at": "2016-10-06T09:43:42.000Z",
    "currency_code": "USD",
    "date": "2013-09-23T00:00:00.000Z",
    "description": "Whole foods",
    "extended_transaction_type": "partner_transaction_type",
    "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
    "id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
    "is_bill_pay": false,
    "is_direct_deposit": false,
    "is_expense": true,
    "is_fee": false,
    "is_income": false,
    "is_international": false,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": false,
    "is_subscription": false,
    "latitude": -43.2075,
    "localized_description": "This is a localized_description",
    "localized_memo": "This is a localized_memo",
    "longitude": 139.691706,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "member_is_managed_by_user": false,
    "memo": "This is a memo",
    "merchant_category_code": 5411,
    "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
    "merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
    "metadata": "some metadata",
    "original_description": "WHOLEFDS TSQ 102",
    "posted_at": "2016-10-07T06:00:00.000Z",
    "status": "POSTED",
    "top_level_category": "Food & Dining",
    "transacted_at": "2016-10-06T13:00:00.000Z",
    "type": "DEBIT",
    "updated_at": "2016-10-07T05:49:12.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

Users

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

User fields

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

Create user

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

Disabling a user means that accounts and transactions associated with it will not be updated in the background by MX. It will also restrict access to that user’s data until they are no longer disabled.

Parameters

Field	Required?
`email`	No
`id`	No
`is_disabled`	No
`metadata`	No

Endpoint:

POST /users

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { Configuration, MxPlatformApi } from 'mx-platform-node';

const configuration = new Configuration({
  basePath: 'https://int-api.mx.com',
  username: 'Client ID',
  password: 'API Key',
  baseOptions: {
    headers: {
      Accept: 'application/vnd.mx.api.v1+json'
    }
  }
});

const client = new MxPlatformApi(configuration);

const requestBody = {
  user: {  
    email: 'email@provider.com',
    id: 'My-Unique-ID',
    is_disabled: false,
    metadata: '{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}'
  }
};

const response = await client.createUser(requestBody);

console.log(response.data);

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
require 'mx-platform-ruby'

::MxPlatformRuby.configure do |config|
  config.username = 'Your Client ID from https://dashboard.mx.com'
  config.password = 'Your API Key from https://dashboard.mx.com'
  config.server_index = 1 # Configure server. 0 for production, 1 for development
end

mx_platform_api = ::MxPlatformRuby::MxPlatformApi.new

request_body = ::MxPlatformRuby::UserCreateRequestBody.new(
  user: ::MxPlatformRuby::UserCreateRequest.new(  
    email: 'email@provider.com',
    id: 'My-Unique-ID',
    is_disabled: false,
    metadata: '{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}'
  )
)

begin
  response = mx_platform_api.create_user(request_body)
  p response
rescue ::MxPlatformRuby::ApiError => e
  puts "Error when calling MxPlatformApi->create_user: #{e}"
end

1
2
3
4
5
6
7
8
9
10
11
12
curl -i -X POST 'https://int-api.mx.com/users' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key' \
  -d '{      
        "user": {        
          "email": "email@provider.com",
          "id": "My-Unique-ID",
          "is_disabled": false,
          "metadata": "{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}"
        }
      }'

1
2
3
4
5
6
7
8
9
{
  user: {  
    email: 'email@provider.com',
    guid: 'USR-d74cb14f-fd0a-449f-991b-e0362a63d9c6',
    id: 'My-Unique-ID',
    is_disabled: false,
    metadata: '{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}'
  }
}

1
2
3
4
5
6
7
8
9
#<::MxPlatformRuby::UserResponseBody
  @user=#<::MxPlatformRuby::UserResponse  
    @email='email@provider.com',
    @guid='USR-d74cb14f-fd0a-449f-991b-e0362a63d9c6',
    @id='My-Unique-ID',
    @is_disabled=false,
    @metadata='{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}'
  >
>

1
2
3
4
5
6
7
8
9
{
  "user": {  
    "email": "email@provider.com",
    "guid": "USR-d74cb14f-fd0a-449f-991b-e0362a63d9c6",
    "id": "My-Unique-ID",
    "is_disabled": false,
    "metadata": "{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}"
  }
}

Delete user

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

Endpoint:

DELETE /users/{user_guid}