Reporting API FAQ

The MX Reporting API enables a partner to programmatically pull MX's data into their system on a per-client basis. This data is requested by providing the date, resource, and action.

Read a more in-depth overview of the Reporting API and view all documentation at developer.mx.com.

You need credentials to access developer.mx.com. If you don't have access, please contact support and request credentials.

Understanding MX architecture

To get the most out of the MX Reporting API, become familiar with MX platform architecture.

Get started here: MX data architecture: the foundation of our platform

What is the reporting response format?

All reporting responses will be in an avro file format. More information about avro can be found on the official avro documentation page. Avro files rely on schemas. When avro data is read, the schema used when writing it is always present. This permits each datum to be written with no per-value overheads, making serialization both fast and small. This also facilitates use with dynamic scripting languages since data, together with its schema, is fully self-describing.

The resources available and the fields included for each are listed in the documentation.

We have included a list of what fields are recorded and written into these log files, but we may add additional fields at any time. See Schema Evolution in the Reporting API Guide for more information.

There will be three daily log files generated for each object, with each action separated into its own file. The actions are: created, updated, and deleted. An object can appear in the files multiple times. For example, if an object is created, updated, and then deleted all on the same day it will appear in all three files.

How do I consume avro files?

Objects on the MX platform are organized in a hierarchy (see MX Architecture). The files must be consumed in a particular order so that the objects are created, updated, and deleted in the proper order.

• First, all files with create actions should be consumed first and in the order shown here.
• Second, all update files should be consumed in the same order.
• Third, the delete files should be consumed in the reverse order listed above. This will ensure that transactions are deleted before the account they belong to is deleted, and so forth.

Can avro files be parsed into other formats?

Avro files are built in a way that they can be parsed and serialized easily into other formats. Avro's documentation provides guidance on parsing these files using different methods.

To the right we show how to read an avro file into a Ruby script and parse the output to json. There is an avro gem available from rubygems.org which we will use to parse the avro file.

The avro file would be parsed into json or csv.

See Parsing avro files for details.

How often are files generated?

Files are generated daily at midnight (UTC), and partners can begin to request them at that time. However, it can take some time for the files to finish being assembled. We recommend waiting until 01:00 UTC before requesting them.

Files are available for seven days after being generated. We recommend that partners pull files daily as soon as they become available, even if they are not able to process the data at that time. MX does not have the ability to regenerate files once they are gone.

See Download Daily Files for details.

Do you have sample data?

Files in the Reporting API are generated from system events which represent user activity and pulling of new account and transactional data. This presents a challenge in the Integrations environment because there are no users actively using the system. Partners who need a more robust set of test data can add their own by having internal test users add accounts and use the system for a few days to generate log events.

See Generating sample data for details.

For example avro files generated from the Reporting API, see Sample avro files.