API Requirements

Accept Header

Requests require an Accept header to specify the version and the encoding of the desired response body. This is the value to the right unless otherwise specified.

_10

Accept: application/vnd.mx.logs.v1+avro

Authentication

Each request is authenticated with an API key that is specific to one MX environment. We'll provide you with separate API keys for the MX Integration and Production environments.

The API key is sent with the request in an MD-API-KEY header, as shown to the right.

The Reporting API is enabled on a per-client basis. Requests made for a client that is not enabled receive a 404 NOT FOUND error.

_10

MD-API-KEY: YOUR_ENVIRONMENT_SPECIFIC_API_KEY

Base URL

All URL endpoints in the Reporting API have a base URL that depends on the environment being addressed.

Integration Environment - used for initial integration testing

_10

https://int-logs.moneydesktop.com/download/:client_id

Production Environment

_10

https://logs.moneydesktop.com/download/:client_id

Data Availability and Null Values

Files are generated daily and are available for up to seven days after generation. It is your responsibility to download them before they are no longer available.

The Reporting API does not provide a full snapshot of historical data. If historical data is desired, MX can generate a one-time data snapshot for an additional cost.

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.

Date and Time Formats

Dates are represented in the following forms:

• Integer datetime fields that end with _at use Unix time format. Unix time is always in UTC.
• String date fields that end with _on use ISO 8601 format without a time component.
• String date fields which end in date or are otherwise unspecified are given in ISO 8601 format without a time component.

Examples

_10

"1970-01-01" # January 1st 1970

_10

90018780 # November 7th 1972 @ 2:13pm UTC

Enabling Resource Groups

Reporting files come in four broad resource groups: Base, Analytics Events, Discovered Accounts, and User Communication. Enabling a group allows you to download daily files in that group. Base files are enabled by default. Contact MX to enable the others.

Group	Resources
Base	accounts beat beat_feedback budgets categories devices goals holdings members notification_profiles tags taggings transactions users
Analytics Events	analytics_events analytics_pageviews analytics_screenviews analytics_timed_events
Discovered Accounts	discovered_accounts discovered_transactions
User Communication	user_communication_profiles

Errors

The Reporting API uses conventional HTTP response 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, etc.) and codes in the 5xx range indicate an error with MX’s servers.

Sometimes simply returning the HTTP status code is not enough to indicate what went wrong. So some endpoints may respond with a body containing more information about the error.

caution

Error codes and messages are for logging and informational purposes only. Error messages may change from time to time.

Error Message Format Example

_10

<error>

_10

<status>code</status>

_10

<message>Error message.</message>

_10

</error>

HTTP Status Code	Definition
200 OK	Everything worked as expected.
403 Forbidden	The IP address doesn't match the API key provided.
404 Not Found	The requested item doesn't exist. Either an id on the URL does not exist, the URL format is invalid, or a resource is requested that is not enabled for that client.
410 Gone	The file is gone and no longer available.
500, 502, 503, 504: server errors	Something went wrong on MX's end.

IP Filtering and Whitelisting

All requests sent to the Reporting API are filtered by IP address. Requests must be made from a whitelisted IP address. Requests made from invalid IP addresses will receive a 403 FORBIDDEN error.

Schema Evolution

MX may add additional fields to the writer schemas included in the response files at any time. This is not considered a breaking change to the Avro files. When new fields are added, this is done with backwards compatibility in mind and the order of the fields may change. This follows the standard set forth by Avro’s schema resolution documentation.

A reader of Avro data, whether from an RPC or a file, can always parse that data because its schema is provided. But that schema may not be exactly the schema that was expected. For example, if the data was written with a different version of the software than it's read, then records may have had fields added or removed.

We call the schema used to write the data the writer’s schema, and the schema that the application expects the reader’s schema. Differences between these should be resolved according to the details outlined in the schema resolution section of Avro’s official documentation.

To support some use cases, MX does include default values for all our fields.

Security

Requests must use TLS 1.2 (or higher) with known secure ciphers. See Authentication & Security for our Platform API for more information.

Object history and revision numbers

Data returned in the Avro files represents a history of changes made to objects on the MX platform throughout the day. This means it is possible for a single daily file to have multiple entries for the same object. In order to enable partners to know the sequence of events, the fields revision and updated_at are included on each resource entry. Use the entry with the latest revision to ensure that the latest version of the object record is consumed.

Versioning and Potentially Breaking Changes

We strive to make API changes backwards-compatible. When we make breaking changes, we increment a 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. The current version is v1.

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

Deprecating Fields and Resources

We sometimes deprecate a field in an object. This is done when a new field is superior to the deprecated one. It is also possible that an entire resource may be deprecated if a new resource is introduced to take its place. A note in the documentation will explain each item that is deprecated, with a recommendation of what to use in its place.

New integrations should avoid using deprecated items. We'll maintain the deprecated fields and resources in the current version to support existing integrations, but existing integrations should also be updated to use the replacement fields and resources. Deprecated items aren't present in the next version of the API.

Enhancements within the current version

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

• New fields added to existing objects (e.g., adding currency_code to the accounts object).
• New resources (e.g., adding goals to the list of available resources).

A new field in an object does not affect any existing integrations since nothing is being removed. You need to ensure your system can process or ignore new fields automatically. Do not rely on a fixed data model in any object. The order in which the fields occur in the file may also vary. The processing of the file should account for these possibilities.

If you're consuming the Avro file directly, parse the included schema each time a file is processed. The desired fields can then be extracted from the data. The process can ignore other fields so that the addition of a new field does not affect the processing of the file.

If you convert the Avro file to a CSV format, ensure a header row is included with such conversions. Parse the header row each time the CSV file is consumed to ensure the order of the fields is read, the desired fields are extracted properly, and any additional fields are ignored.

Enhancements that require advanced notice or a new version

The following changes are breaking changes so they are made in a new version of the API or with advanced notice.

• Removing a field from an object.
• Changing the format of a field, or the contents it returns.
• Removing a resource.
• Adding a new enumerated value to a string that returns a fixed set of values (e.g., transaction status).

It is sometimes necessary to add new values to fields which return enumerated values. Examples include account_subtype in the accounts model and field_type in the credentials model. Allow for the addition of new enumerated values. We will notify you in advance when such additions are anticipated.