Skip to main content

API Request Formats and Requirements

The following information explains requirements for making API requests to the Platform API.

Character Encoding​

Requests to the API must use characters encoded with the UTF-8 standard.

Data Encoding​

MX Technologies is committed to providing high-quality data to accommodate a wide range of scenarios. Due to the financial nature of our data, sometimes special characters such as ', <, >, ", and = will be found in string fields. For example, an account might be identified as Mortgage Loan <= 15 Years. We strongly recommend that clients sanitize and/or encode the output of our API, such as HTML encoding prior to rendering in a web view.

Data Format​

JSON structured data is expected in all requests and returned in all responses, including some errors.

Dates and Times​

Dates and times are always given in ISO 8601 format.

Fields which end in _on are given without a timestamp: 2018-07-18

Fields which end in _at are given with a timestamp: 2015-04-13T12:01:23Z.

Headers​

In addition to the required Authorization header, each request also requires an Accept header: Accept: application/vnd.mx.api.v1+json

POST and PUT requests also require a Content-Type header: 'Content-Type: application/json'

Required Request Body Parameters​

PUT request bodies cannot be empty. Therefore, at least one parameter must be given in a rooted body when making PUT requests, even when no specific parameter is required. If no parameter is given, a 400 Bad Request error will be returned.

Boolean Fields​

The API only accepts true or false as acceptable values when using boolean fields. Do not use 0 or 1 for boolean fields.

Identifiers and Metadata​

All updateable resources created with the API support an optional metadata field. You can use the metadata field to store structured (key-value) data about a resource. For example, you could store a user’s username for your system, their sign-up date, the date and time of their last logon in your system, or all of these. Metadata is not used by MX.

Do not store sensitive information as metadata.

Updateable resources also contain an id field. For instance, you may need to make certain that some resources are created only once or may need to sync data on the MX platform with data on your own platform. In these situations, you can give a unique id to resources created with the MX Platform API. The API will return a 409 Conflict error if a resource is created with an id that already exists.

Pagination​

All endpoints which return lists are paginated. These endpoints also support two query parameters which specify the number of records per page and the page to be returned.

Each response will include a pagination object specifying information on the total number of entries and the current page.


_10
"pagination": {
_10
"current_page": 1,
_10
"per_page": 25,
_10
"total_entries": 2,
_10
"total_pages": 1
_10
}

Query Parameters

ParametersDefinitions
pageThis specifies the page to be returned. Defaults to 1.
records_per_pageThis specifies the number of records to be returned on each page. Defaults to 25. The valid range is from 10 to 1000. If the value exceeds 1000, the default value of 25 will be used instead.

Pagination Fields

FieldDefinition
current_pageThe page delivered by the current response.
per_pageThe number of records delivered with each page.
total_entriesThe total number of records available.
total_pagesThe total number of pages available.

Number Limits​

The limits for decimal numbers are described by their precision and scale (in the format "precision,scale"). Precision refers to the total number of digits. Scale refers to the number of digits to the right of the decimal. For example, 538.46's precision,scale is 5,2.

Member Use Cases​

note

You must work with MX to enable this functionality.

You can opt in to setting the use_cases field in applicable requests so each member has an associated use_case to:

  • Ensure only the data associated with the use case for that member (PFM or Money Movement) is returned.
  • Filter a user’s data through a single use_case, even if data relating to a different use_case is in our system.

Members with the PFM use case will aggregate data the same as before. Our Personal Finance Management and Financial Insights products will only reflect data for members with the PFM use case.

Members with the MONEY_MOVEMENT use case won’t aggregate transaction data.

For how this affects the Connect Widget, see the Connect Widget docs.

If you're using the Connections Widget, you can set the connections_use_case_filter parameter to true so the widget only shows connections (members) that have the use_cases you defined in the same request. For examples, see Filter Connections.

Required Actions​

This work requires MX to enable this functionality. Additionally, for existing integrations, MX will backfill your existing members to set their use_cases field.

You must ensure that each of the following requests sets the use_cases field to either PFM and/or MONEY_MOVEMENT:

  • Any Request Widget URL request that has a widget_type of connect_widget or connections_widget
  • All Create Member requests
  • All Update Member requests. You can use this endpoint to add, edit, or remove a use case, but at least one use case must always remain.

If making a request to Aggregate Member, the associated member must have PFM as a use_case, otherwise a 403 will return.

The following endpoints accept a single use_case query parameter that you can set to either MONEY_MOVEMENT or PFM. For example, if you're using the List Members request, this would look like either GET /members?use_case=PFM or GET /members?use_case=MONEY_MOVEMENT.

On this page