Skip to main content

API Requirements

Base URL​

All URL endpoints in the Migration API have a base. The domain of the base URL will depend on the environment being addressed.

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

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

Integration Server


_10
https://int-migration.moneydesktop.com/{client_id}

Production server


_10
https://migration.moneydesktop.com/{client_id}
_10
_10
https://migration.moneydesktop.com/ACME_Bank/

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://int-migration.moneydesktop.com/Acme_Bank/users/U-39XBF7/migrate/members.json

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.

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

IP filtering​

All requests sent to the Migration 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.


_10
MD-API-KEY: YOUR_ENVIRONMENT_SPECIFIC_API_KEY

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 an HTTP 404 NOT FOUND.

Accept Header​

All requests require an Accept header to specify the version and the encoding of the desired response body:

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

Accept: application/vnd.mx.migration.v1+xml OR Accept: application/vnd.mx.migration.v1+json

Content-Type Header​

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

Content-type: application/vnd.mx.migration.v1+xml OR Content-type: application/vnd.mx.migration.v1+json

Errors​

The Migration 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 — The number of requests from a partner's servers has exceeded MX's safeguard rate limit set for that partner. The rate of requests should be reduced. Requests receiving a 429 status code should be retried once the rate is reduced.
  • 500, 502, 504 Server errors - Something went wrong on MX's end.
  • 503 Service Unavailable - The MX Platform is being updated

Resources​

The Migration API exposes endpoints for Members, Accounts and Transactions. Only Create actions are supported. Members must be attached to a User that has been previously created with the MDX Real Time API Create User request.

  • Users
  • Members - attached to a user.
  • Accounts - attached to a member.
  • Transactions - attached to an account.

Orchestration​

The Migration API requires a partner be responsible for orchestrating requests to the MX Platform. Partners must create records that have dependencies first, following the order shown in the Resources section above.

These records will be created in the MX system, but not be available for aggregation or for display to the user until the migration has been completed. A call to members#finish_migration signals that the migration is complete and that normal operations can begin. The user will be able to provide credentials and MX will start aggregating additional data for that member.

WARNING: All account and transaction migration data should be successfully created within a member before making a request to the Finish Migration endpoint for that member. Partners should NOT create additional accounts or transactions within a member after the Finish Migration endpoint has been used and MX has taken over aggregation for that member. Doing so can result in duplicated or incorrect data. MX is not currently prohibiting these actions, but will start enforcing this restriction at a future point, and partners will receive errors if they attempt to create additional data within a member whose migration has been finished.

Limitations​

The MX system 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. The limit applies to requests being sent to both the Migration API and the MDX Real Time API. MX will work with each partner to set the maximum rate based on that partner's needs.

On this page