Reporting API Implementation Guide

  • Updated

This guide outlines what you must provide to MX to start using the Reporting API.

The Reporting API enables you to track changes for all your users’ data held on the MX platform without having to read this data individually for each user. The Reporting API provides daily change files, in avro format, that indicate how objects have changed throughout the day. 

Terminology

  • GPG (GnuPG) - Tool for generating PGP keys
  • PEM (Privacy Enhanced Mail) - A Base64 encoded DER certificate. PEM certificates are frequently used for web servers as they can easily be translated into readable data using a simple text editor.
  • PGP (Pretty Good Privacy) - An encryption program that provides cryptographic privacy
  • SFTP - Secure File Transfer Protocol

Implementation options

There are two methods to choose from to implement the Reporting API:

  • Setting up an API connection

    An API connection is MX’s preferred method.

    1. Provide a public PGP key. This key allows MX to encrypt the files being shared through the API.
    2. Use the following resources to set up your API:
    3. Work with your TPM to test your connection.

  • Setting up an SFTP connection

    You may have MX deliver your daily reporting files to an SFTP server rather than retrieving them through the API endpoints.

    MX prefers that you use the Reporting API without the use of the SFTP. When using an SFTP, if your IP addresses ever change, you will need to contact MX to have them updated or you will not receive the daily avro files.

    To continue with the SFTP connection, please provide the following to your TPM:

    1. A URL for MX to use to connect to your SFTP server

      If possible, it is preferred that you use a non-standard port for your SFTP server.

    2. A public PGP key. This key allows MX to encrypt the files being shared through the API.
    3. SFTP credentials: A username and password for authentication to the SFTP server (Currently MX does not support SSH keys for connection.)
    4. Any IP addresses for your SFTP server, so that MX can whitelist them

If a particular resource has no data for a given day, an avro file with headers but no records will still be generated.

Providing a public PGP key

To enable the Reporting API, you must provide a public PGP key in PEM format. MX uses this key to encrypt the files you will receiving.

If you are unsure how to generate this key, your development and IT teams may be able to help.

  • Pretty Good Privacy (PGP) is an encryption program that provides cryptographic privacy and authentication for data communication. PGP is used for signing, encrypting, and decrypting texts, e-mails, files, directories, and to increase the security of e-mail communications.

    Learn more about PGP.

    MX supports GPG keys in addition to PGP keys.

  • If you are unfamiliar with using PGP keys, reach out to your development and IT teams, or ask your TPM or CSC at MX for more information.

    There are many tools available for generating PGP keys, including the commonly used GnuPG. GnuPG is a complete and free implementation of the OpenPGP standard.

Need more help?

Need more than what’s available here?

  • Contact your Technical Project Manager (TPM) or Client Strategy Consultant (CSC)
  • Contact Support

Was this article helpful?

0 out of 0 found this helpful