MDX Real Time - MX Documentation

MDX Real Time is the API you use to create the user, member, account, transaction, and holding resources in the MX system. It supports both XML and JSON encoding of the request and response bodies. Integrations that use the MDX Real Time API also require the use of single sign-on (SSO) to authenticate users and open software.

Authentication

Each MDX Real Time request is authenticated with an API key. The API key is specific to one MX environment. You’re provided with separate API keys for the MX integration and production environments. The API key is provided in an MD-API-KEY header, like this: MD-API-KEY: YOUR_ENVIRONMENT_API_KEY If you make a request with an invalid API key, you receive the HTTP status code 401 Unauthorized.

Base URL

All endpoints in the MDX Real Time API have a base URL that includes the ID of the client that the user belongs to. The domain of the base URL depends on the environment being addressed:

Integration environment: Initial integration testing is done in the integration environment. The base URL for this environment is https://int-live.moneydesktop.com/{client_id}.
Production environment: The base URL for the production environment is https://live.moneydesktop.com/{client_id}.

Here’s an example of a base URL for ACME Bank in the production environment: https://live.moneydesktop.com/ACME_Bank/

Data Encryption

The MDX Real Time API is served over HTTPS. To ensure data privacy, unencrypted HTTP requests are not supported.

Data Management Responsibility

The MDX Real Time API includes all CRUD operations for each resource. It is your responsibility to integrate all of these endpoints to manage data that is sent to MX’s servers.

HTTP Status Codes

The MDX Real Time API uses conventional HTTP status codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with the MX Platform. Refer to Table 1 for a summary of HTTP status codes in MDX Real Time.

Table 1. HTTP status codes in MDX Real Time

HTTP Status Code	Description
200 OK	Everything worked as expected.
204 No Content	Everything worked, but no content is being returned. Typically returned from a DELETE request.
400 Bad Request	There was an invalid or malformed request body.
401 Unauthorized	No valid API key was provided.
403 Forbidden	The IP address doesn’t match the API key provided.
404 Not Found	The requested item doesn’t exist.
409 Conflict	The object being created already exists. Can only be returned from a POST request.
422 Unprocessable Entity	The data provided doesn’t meet acceptable criteria. Typically returned from a POST or PUT request when attempting to add a field with more characters than allowed in the data spec, or when a field contains invalid characters.
429 Too Many Requests	The maximum number of concurrent connections or rate limit has been exceeded. For more information, see Rate Limiting.
500, 502, 504 Server errors	Something went wrong on MX’s end.
503 Service Unavailable	The MX platform is being updated.

Sometimes the HTTP status code isn’t enough to indicate what went wrong. To compensate for this, you can supplement more information with an additional error message in the response body if needed. Each error consists of a code and a message. See Table 2 for details.

Table 2. Additional error messages

Code	HTTP Status	Description
4001	400	One or more parameters are invalid.
4002	400	One or more parameters are missing.
4003	400	One or more of the credentials provided in this request aren’t supported by this institution.
4221	422	One or more parameters has an invalid ID format.
5001	500	No such institution was found for member creation.

Here’s an example of the error response body:

  <error>
    <code>4001</code>
    <message>One or more parameters were invalid</message>
  </error>

Headers

All MDX Real Time requests require Accept and Content-Type headers. Refer to Table 3 for the specifics of each.

Table 3. MDX Real Time headers

Header	Set value to	Description
`Accept`	`application/vnd.moneydesktop.mdx.v5+xml` or `application/vnd.moneydesktop.mdx.v5+json`	Include this header in the response to specify the encoding and version being requested.
`Content-Type`	`application/vnd.moneydesktop.mdx.v5+xml` or `application/vnd.moneydesktop.mdx.v5+json`	Include this header in POST and PUT requests to specify the format of the request body.

IP Whitelisting

All requests to MX APIs must come from a whitelisted IP address, which is configured via the client dashboard. Any request from a non-whitelisted IP address returns a 403 Forbidden error. Since IP addresses outside of the United States are normally not permissible, any requests for non-US IPs are manually investigated before they’re approved. If we have any questions or need further details from you, we’ll contact you via email.

MX IP Address Ranges

MX maintains multiple data centers for failover and load balancing purposes. Each data center has a range of IP addresses, and any IP address in these ranges can be active. The DNS entries for MX API URLs can resolve to any IP address in our ranges and can change at any time. If you choose to whitelist the IP addresses that the API URLs are allowed to resolve to, you must whitelist all of the IP address ranges. Refer to the following table for a list of these ranges:

CIDR	Range
64.77.254.32/27	30 addresses from 64.77.254.33 to 64.77.254.62
66.43.0.0/22	1,022 addresses from 66.43.0.1 to 66.43.3.254
68.142.151.128/26	62 addresses from 68.142.151.129 to 68.142.151.190
97.75.178.32/27	30 addresses from 97.75.178.33 to 97.75.178.62
146.75.94.131/32	1 address 146.75.94.131
170.178.148.0/22	1,022 addresses from 170.178.148.0 to 170.178.151.255
192.41.25.128/26	62 addresses from 192.41.25.129 to 192.41.25.190
192.41.58.128/26	62 addresses from 192.41.58.129 to 192.41.58.190

DDoS Protection

MX provides an on-demand Distributed Denial of Service (DDoS) protection service using Akamai’s DDoS scrubbing center. In the event of a DDoS attack, traffic is only redirected to Akamai. We only redirect inbound requests (requests coming into MX), while outbound requests (requests sent to you or your partners) still come from the existing IP ranges. Outbound requests include, but are not limited to, mobile upstream events, webhooks, and aggregation requests. Although we only redirect inbound requests, if you have firewall rules that prevent outbound connections to whitelisted IP addresses, you must add those to avoid service disruption during a DDoS mitigation event. Visit Akamai’s official documentation to learn more about the IP addresses that may be used in the event of a DDoS attack, and subscribe to this page if you want to be notified when changes occur.

Rate Limiting

The MDX Real Time API limits you to a specific number of requests per second (RPS) based on your API key. MX will work with you to set the maximum rate based on your needs, but the standard thresholds for requests per second are:

GET: 2,000 RPS
POST: 750 RPS
PUT: 750 RPS
DELETE: 150 RPS

When you exceed the maximum number of concurrent connections or requests per second, the 429 Too Many Requests error is triggered. Retry these requests after the rate limit resets.

Orchestration

The MDX Real Time API requires partner responsibility for orchestrating requests to the MX Platform. This means you must create records that have dependencies first. For example, you must create an account before you create a transaction under that account. When deleting records, a cascading delete removes all child records in the hierarchy. For example, it’s not necessary to delete transactions attached to an account before deleting the account.

Security

Requests must use TLS 1.2 or higher with known secure ciphers.

URL Extension

The encoding of the response body is specified by an extension on the URL. If the extension is omitted, XML is used. Here’s an example of a request URL for a JSON response body: https://live.moneydesktop.com/your_client_id/users.json

Versioning

We strive to make API changes backwards-compatible. When we make breaking changes, we increment the version. Because of this, it’s best to specify the version of the API with each request. Versions are passed as part of the request’s Accept and Content-Type headers. Requests that don’t specify a version get the latest representation of resources, and unsupported endpoints return an HTTP status of 404 Not Found. Non-breaking updates include new fields, endpoints, and processes. Because we may introduce new elements at any time, your systems should be designed to automatically process or ignore new fields rather than relying on a fixed data model. Note that while we may recommend improved processes, we will continue to support previous methods throughout the current version. Breaking updates include removing fields or endpoints, changing field formats, or implementing major process shifts. These updates are restricted to new API versions and are communicated to you before the new versions are released. We occasionally add new enumerated values to fields (like account_subtype or field_type), and will communicate to you the anticipation of such additions as they occur. Please ensure your integration is prepared to accept these new values.

​Authentication

​Base URL

​Data Encryption

​Data Management Responsibility

​HTTP Status Codes

​Headers

​IP Whitelisting

​MX IP Address Ranges

​DDoS Protection

​Rate Limiting

​Orchestration

​Security

​URL Extension

​Versioning