Skip to main content

MDX Real Time

MDX Real Time is used to create a resource in the MX system. All partners will use MDX Real Time to create users. Partners can also use MDX Real Time to create members, accounts, transactions, and holdings. The real-time "push" of account, transaction, and holding data from a partner to MX creates an ideal integration for the best user experience.

MDX Real Time supports both XML and JSON encoding of the request and response bodies.

Authentication​

Each request is authenticated with an API key. The API key is specific to one MX environment. Each partner will be provided with separate API keys for the MX Integration and Production environments.

The API key is provided in an MD-API-KEY header:

MD-API-KEY: YOUR_ENVIRONMENT_SPECIFIC_API_KEY

If a request is made with an invalid API key, an HTTP 401 UNAUTHORIZED response code will be returned.

Base URL​

All URL endpoints in the MDX Real Time API have a base. The domain of the base URL will depend on the environment being addressed:

Integration Server (for initial integration testing)

https://int-live.moneydesktop.com/:client_id

Production Server

https://live.moneydesktop.com/:client_id

The client ID of the client the user belongs to is also specified in the base URL of all requests, as in the following example:

https://live.moneydesktop.com/ACME_Bank/

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. Partners are responsible for integrating all of these endpoints to manage data that is sent to MX's servers.

Deprecated Fields and Endpoints​

MX will sometimes deprecate a field in an object, or deprecate an entire endpoint. This is done when a new field or endpoint is superior to the deprecated one. A note will explain each item that is deprecated, with a recommendation of what to use in its place.

New partner integrations should avoid using deprecated items. MX will maintain the deprecated fields and endpoints to support existing integrations, but we do recommend that existing integrations also update to use the new processes when convenient.

Errors​

Example Error Response Body


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

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 (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with the MX Platform.

HTTP status code summary

  • 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: Invalid or malformed request body.
  • 401 Unauthorized: No valid API key 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 does not 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:
    • This error is triggered when exceeding the maximum number of concurrent connections, or the rate limit for requests per second (rps) is surpassed. Requests receiving a 429 status code should be retried once the rate limit window has expired.
    • To prevent this error, decrease the number of concurrent connections or the number of requests per second. Rate limiting is applied per client with the following thresholds:
      • GETs: 2000/rps
      • POSTs: 750/rps
      • PUTs: 750/rps
      • DELETEs: 150/rps
    • Individual features may implement specific rate limit overrides, please see feature documentation for more information.
  • 500, 502, 504 Server errors: Something went wrong on MX's end.
  • 503 Service Unavailable: The MX Platform is being updated.

Sometimes simply returning the HTTP status code is not enough to indicate what went wrong. To compensate for this, endpoints may respond with a body containing more information about the error. Each error consists of a code and a message:

Additional Error Codes​

info

Error codes and messages are for logging and for informational purposes only and may change from time to time. Do not check for specific codes or messages as this may break your integration. The HTTP status response codes are sufficient for an integration workflow and processing of the error response body is not needed.

CodeHTTP StatusDescription
4001400One or more parameters were invalid.
4002400Required parameter(s) missing.
4003400One or more of the credentials provided in this request are not supported by this institution.
4221422One or more parameters had an invalid id format.
5001500Institution not found for member create.

Escaped Characters​

If using JSON format, please use the standard JSON escapement for double quotes (") if included in any text/string fields.

If using XML format, please ensure it is valid XML by using standard XML escapement for all XML-reserved characters, or by wrapping these text/string fields that might contain these characters in CDATA tags.

Headers​

Accept header​

All requests require an accept header to specify the version and the encoding of the desired response body.

Accept: application/vnd.moneydesktop.mdx.v5+xml

OR

Accept: application/vnd.moneydesktop.mdx.v5+json

The encoding specified in the Accept header must match the encoding specified in the URL extension.

Content-Type header​

POST and PUT requests require a Content-Type header to specify the format of the request body.

Content-type: application/vnd.moneydesktop.mdx.v5+xml

OR

Content-type: application/vnd.moneydesktop.mdx.v5+json

IP filtering​

All requests sent to the MDX Real Time API are filtered by IP address. All IP addresses where API requests originate must be whitelisted. Requests made from invalid IP addresses will receive an HTTP 403 FORBIDDEN.

Limitations​

The MDX Real Time API limits partners to a specific number of requests per second. The limit is based on the partner's API key so it will apply to all requests from the partner for all clients. MX will work with each partner to set the maximum rate based on that partner's needs.

Orchestration​

The MDX Real Time API requires a partner be responsible for orchestrating requests to the MX Platform. Partners must create records that have dependencies first. For example, an account must be created before creating transactions under that account.

When deleting records, a cascading delete will be performed to delete all records under that record in the hierarchy. For example, it is 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 will be used.

Example 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 is best to specify the version of the API with each request. Versions are passed as part of the request's Accept header and Content-Type header.

Requests that don't specify a version will get the latest representation of resources, and unsupported endpoints will simply return a HTTP 404 NOT FOUND.

Enhancements Within the Current Version​

MX continually makes enhancements to our APIs. Breaking changes are reserved for a new version, but non-breaking additions are regularly made in the current version. These include:

  • New fields added to existing objects (e.g. Adding currency_code to accounts).
  • New endpoints added (e.g. Adding Create Holding).
  • New processes. At times MX will recommend a new process for accomplishing a task. The new process is an improvement on the previous process and is recommended for all integrations, but MX will continue to support the old process throughout the current version of the API.

Partners should expect these enhancements to occur regularly. A new field in an object should not affect any existing integrations since nothing is being removed, but partners need to ensure their system can process or ignore new fields automatically. Partners should not rely on a fixed data model in any object.

Enhancements that will Require a New Version or Advanced Notice​

The following changes are breaking changes so they will only be made in a new version of the API, or with advanced notice to partners.

  • Removing a field from an object.
  • Changing the format of a field, or the contents it returns.
  • Removing an endpoint.
  • Adding a new Enumerated Value to a string that returns a fixed set of values (e.g. transaction status).
  • Major process changes (e.g. adding the requirement to use a new endpoint).

It is sometimes necessary to add new values to fields which return enumerators. Examples include account_subtype in the accounts model and field_type in the credentials model. Partner developers should allow for the addition of new enumerated values. MX will notify partners in advance when such additions are anticipated.

On this page