What is the Reporting API?

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.

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 below. 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 the schema evolution section for more information.

If a particular resource has no data for a given day, an Avro file with headers but no body will be generated and made available for retrieval.


Things You Need to Know


Accept Header

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

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


Authentication

Each request is authenticated with an API key that 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 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 will receive a 404 NOT FOUND error.

MD-API-KEY: YOUR_ENVIRONMENT_SPECIFIC_API_KEY


Base URL

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

Production Environment

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

Integration Environment (for initial integration testing)

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

Consuming Daily Reporting Files

Objects on the MX platform are organized in a hierarchy. This means that your systems must consume daily reporting files in a particular order so that the objects are created, updated, and deleted in the proper order in your data store/warehouse.

First, you must consume all files with create actions in this order:

  1. Users
  2. Members
  3. Accounts
  4. Transactions
  5. Holdings
  6. Categories
  7. Tags
  8. Taggings
  9. Goals
  10. Budgets
  11. Notification Profiles
  12. Beat
  13. Beat Feedback
  14. Devices
  15. Analytics Events
  16. Analytics Page Views
  17. Analytics Screen Views
  18. Analytics Timed Events

Second, you must consume all update files in the same order as above.

Third, you must consume all delete files in the reverse order. This ensures transactions are deleted on your systems before the account they belong to is deleted, and so forth.


Data Availability and Null Values

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

"1970-01-01"    # January 1st 1970
90018780        # November 7th 1972 @ 2:13pm UTC

Deprecated Fields and Resources

MX will 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 partner integrations should avoid using deprecated items. MX will 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 will not be present in the next version of the API.


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. To compensate for this, endpoints may respond with a body containing more information about the 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.

Error message format

1
2
3
4
<error>
  <status>code</status>
  <message>Error message.</message>
</error>

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. 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 is 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.

In order to support some use cases, MX does include default values for all of our fields.


Security

Requests must use TLS 1.2 (or higher) with known secure ciphers. See MX Authentication for more information (this link currently points to MX’s older documentation site, which requires a login).


Versioning and Potentially Breaking Changes

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. The current version is v1.

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

Enhancements within the current version

MX continually makes enhancements to our APIs. Partners should 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 should not affect any existing integrations since nothing is being removed. Partners need to ensure their system can process or ignore new fields automatically. Partners should not rely on a fixed data model in any object. The order in which the fields will occur in the file may also vary. The processing of the file should account for these possibilities.

Partners consuming the Avro file directly should parse the included schema each time a file is processed. The desired fields can then be extracted from the data. The process should be able to ignore other fields so that the addition of a new field will not affect the processing of the file. See the schema evolution section of the reporting guide for further information.

Partners who convert the Avro file to a CSV format should ensure a header row is included with such conversions. The header row should be parsed 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 will require advanced notice or a new version

The following changes are breaking changes so they will only be made in a new version of the API, or with advanced notice to partners.

  • 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. Partners should allow for the addition of new enumerated values. MX will notify partners in advance when such additions are anticipated.


Reporting Guide

For information on best practices, dealing with large files, consuming files, and testing, see our Reporting guide.

Reporting Guide

Base Resources


Accounts

An account represents a financial account, e.g., a user’s checking or savings account. A member may have more than one account associated with it. For instance, a user may have both a checking and savings account associated with one Chase login and would therefore have two accounts associated with that member.

Daily reporting files for accounts reflect changes resulting from background aggregation or from interactions with any of the following MX products (some links point to an external MX documentation site):

Account Fields

Field Name Data type Definition
account_number String The account number associated with the account. This will typically be a masked or partial account number.
apr Decimal The annual percentage rate associated with the account.
apy Decimal The annual percentage yield associated with the account.
available_balance Decimal The balance that is available for use in asset accounts like checking and savings. PENDING transactions are typically taken into account with the available balance, but this may not always be the case.

available_balance will usually be a positive value for all account types, determined in the same way as the balance field.
available_credit Decimal The amount of credit available for use in liability accounts like credit cards and lines of credit. PENDING transactions are typically taken into account with available credit, but this may not always be the case.

available_credit will usually be a positive value for all account types, determined in the same way as the balance field.
balance Decimal The current balance of the account. PENDING transactions are typically not taken into account with the current balance, but this may not always be the case. This is the value used for the account balance displayed in MX UIs.

The balance will usually be a positive value for all account types. Asset-type accounts (CHECKING, SAVINGS, INVESTMENT) may have a negative balance if they are in overdraft. Debt-type accounts (CREDIT_CARD, LOAN, LINE_OF_CREDIT, MORTGAGE) may have a negative balance if they are overpaid.
cash_advance_apr Decimal APR values for cash advances. Value is a percentage (e.g. 2.99% is passed as 2.99).
cash_balance Decimal The cash balance of the account.
cash_surrender_value Decimal The sum of money paid to the policyholder or annuity holder in the event the policy is voluntarily terminated before it matures, or the insured event occurs.
created_at Integer The date and time at which the account was created.
credit_limit Decimal The credit limit associated with the account.
day_payment_is_due Integer The day of the month the payment is due. For example, the 14th is passed as 14.
death_benefit Decimal The amount paid to the beneficiary of the account upon death of the account owner.
guid String The unique identifier for the account. Defined by MX.
has_monthly_transfer_limit Boolean This account limits the number of transfers each month. This is associated with government regulation D.
holdings_value Decimal The sum of all long holdings within this account, not including any that are shorted and not including cash.
id String The unique partner-defined identifier for the account
institution_guid String The unique identifier for the institution that this account is associated with. Defined by MX.
insured_name String The name of the insured individual.
interest_rate Decimal The interest rate associated with the account.
is_closed Boolean This indicates whether an account has been closed.
is_hidden Boolean This indicates whether the account is hidden. Defaults to false.
is_internal Boolean This indicates whether the account belongs to a client’s default institution.
is_personal Boolean This indicates whether the account is personal.
last_payment_at Integer The date and time of the most recent payment on the account.
last_payment_on String The date of the account’s most recent payment.
last_payment Decimal The amount of the most recent payment made on the account.
loan_amount Decimal The amount of the loan associated with the account.
matures_at Integer The date and time at which the account matures, given as a Unix timestamp.
matures_on String The date on which the account will mature.
member_guid String The unique identifier for the member associated with the account. Defined by MX.
member_id String The unique, partner-defined, identifier for the member associated with this account.
member_is_managed_by_user Boolean This indicates whether the associated member is managed by the user or the MX partner.
metadata String Additional information a partner can store on the account.
minimum_balance Decimal The minimum balance associated with the account.
minimum_payment Decimal The minimum payment required for an account. This can apply to any debt account.
monthly_transfer_count Integer The number of limited transfers that have occurred during the current month. Typically users will incur a fee for going over six transfers from a limited transfer account in a given month. This is associated with government regulation D.
name String The human-readable name for the account.
nickname String An alternate name for the account.
original_balance Decimal The original balance associated with the account. This will always be positive.
pay_out_amount Decimal The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy.
payment_due_at Integer The date and time at which the next payment is due on the account. Represented as a Unix Epoch datetime (e.g. 1479166089).
payment_due_on String The date on which the next payment is due on the account.
payoff_balance Decimal The payoff balance for a debt account. This will normally be a positive number.
pending_balance Decimal The available balance after accounting for pending transactions.
premium_amount Decimal The insurance policy’s premium amount.
property_type String The property type of the account, if applicable. See the section on account property types below.
revision Integer The revision number of the account record.
started_at Integer The date and time at which a debt account was started.
started_on String The date on which a debt account was started.
statement_balance Decimal The balance at the end of the account’s last statement period.
statement_on String The closing date — i.e., the statement compilation date — of the account’s last billing cycle.
sub_type String The account’s subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY. See the section on account subtypes below.
total_account_value Decimal The sum of the long and short positions, the sweep account and/or cash balance, and any margin debt associated with a particular account. This amount includes the market value of all positions held in the account and is reduced by any debit balance and the amount of short options positions that are “in the money”. This may sum to a negative value, and it does not represent an account balance.
type String The general or parent type of the account. See the section on account types below.
updated_at Integer The date and time at which the account was most recently updated.
user_guid String The unique identifier for the user the account is associated with. Defined by MX.
user_id String The unique, partner-defined, identifier for the user associated with this account.

Account Types and Subtypes

Parent types
ANY (not provided by data partner or invalid number provided)
CHECKING
SAVINGS
LOAN
CREDIT_CARD
INVESTMENT
LINE_OF_CREDIT
MORTGAGE
PROPERTY
CASH
INSURANCE
PREPAID
CHECKING_LINE_OF_CREDIT

Subtypes

Subtype Parent type
MONEY_MARKET SAVINGS
CERTIFICATE_OF_DEPOSIT SAVINGS
AUTO LOAN
STUDENT LOAN
SMALL_BUSINESS LOAN
PERSONAL LOAN
PERSONAL_WITH_COLLATERAL LOAN
HOME_EQUITY LOAN
PLAN_401_K INVESTMENT
PLAN_403_B INVESTMENT
PLAN_529 INVESTMENT
IRA INVESTMENT
ROLLOVER_IRA INVESTMENT
ROTH_IRA INVESTMENT
TAXABLE INVESTMENT
NON_TAXABLE INVESTMENT
BROKERAGE INVESTMENT
TRUST INVESTMENT
UNIFORM_GIFTS_TO_MINORS_ACT INVESTMENT
PLAN_457 INVESTMENT
PENSION INVESTMENT
EMPLOYEE_STOCK_OWNERSHIP_PLAN INVESTMENT
SIMPLIFIED_EMPLOYEE_PENSION INVESTMENT
SIMPLE_IRA INVESTMENT
BOAT LOAN
POWERSPORTS LOAN
RV LOAN
HELOC LOAN
PLAN_ROTH_401_K INVESTMENT
FIXED_ANNUITY INVESTMENT
VARIABLE_ANNUITY INVESTMENT
VEHICLE_INSURANCE INSURANCE
DISABILITY INSURANCE
HEALTH INSURANCE
LONG_TERM_CARE INSURANCE
PROPERTY_AND_CASUALTY INSURANCE
UNIVERSAL_LIFE INSURANCE
TERM_LIFE INSURANCE
WHOLE_LIFE INSURANCE
ACCIDENTAL_DEATH_AND_DISMEMBERMENT INSURANCE
VARIABLE_UNIVERSAL_LIFE INSURANCE
HSA INVESTMENT
TAX_FREE_SAVINGS_ACCOUNT INVESTMENT
INDIVIDUAL INVESTMENT
REGISTERED_RETIREMENT_INCOME_FUND INVESTMENT
CASH_MANAGEMENT_ACCOUNT INVESTMENT
EMPLOYEE_STOCK_PURCHASE_PLAN INVESTMENT
REGISTERED_EDUCATION_SAVINGS_PLAN INVESTMENT
PROFIT_SHARING_PLAN INVESTMENT
UNIFORM_TRANSFER_TO_MINORS_ACT INVESTMENT
PLAN_401_A INVESTMENT
SARSEP_IRA INVESTMENT
FIXED_ANNUITY_TRADITIONAL_IRA INVESTMENT
VARIABLE_ANNUITY_TRADITIONAL_IRA INVESTMENT
SEPP_IRA INVESTMENT
INHERITED_TRADITIONAL_IRA INVESTMENT
FIXED_ANNUITY_ROTH_IRA INVESTMENT
VARIABLE_ANNUITY_ROTH_IRA INVESTMENT
INHERITED_ROTH_IRA INVESTMENT
COVERDELL INVESTMENT
ADVISORY_ACCOUNT INVESTMENT
BROKERAGE_MARGIN INVESTMENT
CHARITABLE_GIFT_ACCOUNT INVESTMENT
CHURCH_ACCOUNT INVESTMENT
CONSERVATORSHIP INVESTMENT
CUSTODIAL INVESTMENT
DEFINED_BENEFIT_PLAN INVESTMENT
DEFINED_CONTRIBUTION_PLAN INVESTMENT
EDUCATIONAL INVESTMENT
ESTATE INVESTMENT
EXECUTOR INVESTMENT
GROUP_RETIREMENT_SAVINGS_PLAN INVESTMENT
GUARANTEED_INVESTMENT_CERTIFICATE INVESTMENT
HRA INVESTMENT
INDEXED_ANNUITY INVESTMENT
INVESTMENT_CLUB INVESTMENT
IRREVOCABLE_TRUST INVESTMENT
JOINT_TENANTS_BY_ENTIRITY INVESTMENT
JOINT_TENANTS_COMMUNITY_PROPERTY INVESTMENT
JOINT_TENANTS_IN_COMMON INVESTMENT
JOINT_TENANTS_WITH_RIGHTS_OF_SURVIVORSHIP INVESTMENT
KEOUGH_PLAN INVESTMENT
LIFE_INCOME_FUND INVESTMENT
LIVING_TRUST INVESTMENT
LOCKED_IN_RETIREMENT_ACCOUNT INVESTMENT
LOCKED_IN_RETIREMENT_INVESTMENT_FUND INVESTMENT
LOCKED_IN_RETIREMENT_SAVINGS_ACCOUNT INVESTMENT
MONEY_PURCHASE_PLAN INVESTMENT
PARTNERSHIP INVESTMENT
PLAN_409_A INVESTMENT
PLAN_ROTH_403_B INVESTMENT
REGISTERED_DISABILITY_SAVINGS_PLAN INVESTMENT
REGISTERED_LOCKED_IN_SAVINGS_PLAN INVESTMENT
REGISTERED_PENSION_PLAN INVESTMENT
REGISTERED_RETIREMENT_SAVINGS_PLAN INVESTMENT
REVOCABLE_TRUST INVESTMENT
ROTH_CONVERSION INVESTMENT
SOLE_PROPRIETORSHIP INVESTMENT
SPOUSAL_IRA INVESTMENT
SPOUSAL_ROTH_IRA INVESTMENT
TESTAMENTARY_TRUST INVESTMENT
THRIFT_SAVINGS_PLAN INVESTMENT
INHERITED_ANNUITY INVESTMENT
CORPORATE_ACCOUNT INVESTMENT
LIMITED_LIABILITY_ACCOUNT INVESTMENT

Account Property Types

Property type
REAL_ESTATE
VEHICLE
ART
JEWELRY
FURNITURE
APPLIANCES
COMPUTER
ELECTRONICS
SPORTS_EQUIPMENT
MISCELLANEOUS

Beat

Beats (also called insights) are part of MX’s Pulse/Insights personal financial management product (this link points to an external MX documentation site).

Beat Fields

Field name Data type Definition
account_guids Array An array of account GUIDs that are relevant to the information delivered in the beat.
account_ids Array An array of partner-defined identifiers for accounts that are relevant to the information delivered in the beat.
active_at Integer The date and time the beat became active.
created_at Integer The date and time this beat was created.
description String The human-readable information being delivered to the end user.
digest String A unique identifier derived from inputs to the beat which ensures beats are not duplicated.
displayed _at Integer The date and time at which the beat was displayed to the end user.
guid String The unique identifier for the beat. Defined by MX.
has_been_displayed Boolean This indicates whether the beat has been displayed to the end user.
html_description String The beat’s description, delivered as HTML.
html_title String The beat’s title, delivered as HTML.
is_deleted Boolean This indicates whether the beat has been deleted.
is_dismissed Boolean This indicates whether the beat has been dismissed.
is_relevant Boolean This indicates whether a beat still contains information that is relevant, meaningful, or useable to the end user. For example, an OverdraftWarning will have is_relevant set to false if a large deposit is made into the associated account after the beat was created. Any beat which has already been displayed to or dismissed by the end user will be set to false. There are numerous examples and conditions.
primary_account_guid String The unique identifier for the account most relevant to the information delivered in the beat.
primary_account_id String The unique partner-defined identifier for the account most relevant to the information delivered in the beat.
primary_transaction_guid String The unique identifier for the transaction most relevant to the information delivered in the beat.
primary_transaction_id String The unique partner-defined identifier for the transaction most relevant to the information delivered in the beat.
template String A short label for the type of beat being delivered, e.g., SubscriptionPriceIncrease or MonthlyCategoryTotal.
title String The title for the specific beat, e.g., Price Increase or Paycheck Deposit.
transaction_guids Array An array of transaction GUIDs that are relevant to the information delivered in the beat.
transaction_ids Array An array of partner-defined transaction identifiers that are relevant to the information delivered in the beat.
updated_at Integer The date and time this beat was most recently updated.
user_guid String The unique identifier for the user to which the beat belongs. Defined by MX.
user_id String The unique partner-defined identifier for the user to which the beat belongs.

Beat Templates

Template
BillAmountNotStandard
CategorySpending
CheckDeposit
DebtPaymentReminder
DepositAggregate
DuplicatePayment
GovernmentDeposit
IntroducePulse
LargeDeposit
MonthlySavings
MonthlySpendComparison
NewSubscription
OverdraftWarning
PayrollAdvance
PayrollDeposit
SubscriptionPriceIncrease
TaxDeposit
UserFeedback

Beat Feedback

Beat feedback is part of MX’s Pulse/Insights personal financial management product (this link points to an external MX documentation site).

Beat Feedback Fields

Field name Data type Definition
beat_guid String The unique identifier for the beat associated with this feedback. Defined by MX.
comments String The feedback provided by the end user.
created_at Integer The date and time associated with this beat feedback.
guid String The unique identifier for the beat feedback. Defined by MX.
rating Integer The rating provided by the end user. 1 is the lowest rating, 5 is the highest. 0 means no rating was provided.
template String A short label for the type of beat being delivered, e.g., NotifySalaryDeposit or SumSpendingCategory.
updated_at Integer The date and time at which the beat feedback was last updated.
user_guid String The unique identifier for the user associated with the beat feedback. Defined by MX.
user_id String The partner-defined identifier for the user associated with the beat feedback.

Budgets

Budgets represent an end users monthly budget for a given category. Budgets are offered as part of the following MX products:

Budget Fields

Field name Data type Definition
amount Integer The monthly amount allotted to this budget.
category_guid String The unique identifier for the category associated with this budget. Defined by MX.
created_at Integer The date and time the budget was created.
guid String The unique identifier for the budget. Defined by MX.
is_exceeded Boolean This indicates that the budget has been exceeded.
is_off_track Boolean This indicates that the projected total monthly spending in the associated category exceeds 105% of the budgeted amount.
metadata String Additional information a partner can store on the budget.
name String The name of the budget. This is the same as the name of the spending category that the budget is associated with.
parent_guid String The unique identifier for the parent budget. Defined by MX.
projected_spending Decimal The projected amount of spending for the budget.
revision Integer The revision number of the budget record.
transaction_total Decimal The cumulative amount of all transactions associated with this budget.
updated_at Integer The date and time this budget was most recently updated.
user_guid String The unique identifier for the user the budget is associated with. Defined by MX.
user_id String The unique, partner-defined identifier for the user the budget is associated with.

Categories

Daily reporting files for categories reflect changes in custom transaction categories created by end users with the following MX products (some links point to an external MX documentation site):

Category Fields

Field name Data type Definition
created_at Integer The date and time the category was created. This field will always be null when is_default is true.
guid String The unique identifier of the category. Defined by MX.
is_default Boolean This indicates whether the category is an MX-created default category. This will always be false for custom categories.
is_income Boolean This indicates whether the category represents income. This will always be false for custom categories.
metadata String Addition information a partner can store on the category.
name String The name of the category.
parent_guid String The unique identifier for the parent category. Defined by MX.
revision Integer The revision number of the category record.
updated_at String The date and time the category was last updated. This field will always be null when is_default is true.
user_guid Integer The unique identifier of the user this category is associated with. Defined by MX.
user_id String The unique, partner-defined identifier of the user this category is associated with.

Devices

Devices represent devices using the Helios Mobile App.

Device Fields

Field name Data type Definition
guid String The unique identifier of the device. Defined by MX.
make String The name of the device’s manufacturer.
model String The model of the device.
os_name String The name of the operating system that the device is running.
os_version String The operating system version that the device is running.
updated_at Integer The date and time the device record was last updated.
user_guid String The unique identifier for the user the device is associated with. Defined by MX.
user_id String The unique, partner-defined identifier for the user the device is associated with.

Goals

Goals represent savings or payment goals created with the following MX products (some links point to an external MX documentation site):

Goal Fields

Field name Data type Definition
account_guid String The unique identifier for the account the goal is associated with. Defined by MX.
amount Decimal The amount of the goal.
completed_at Integer The date and time the goal was completed.
completed_on String The date the goal was completed.
created_at Integer The date and time the goal was created.
created_by String The source that created the goal. Can be SYSTEM, USER, or null.
created_on String The date the goal was created.
current_amount Decimal The current amount that has been committed to the goal.
goal_type String The type of the goal (SAVE_AMOUNT or PAYOFF).
guid String The unique identifier for the goal. Defined by MX.
has_been_spent Boolean This indicates that the goal has been spent.
is_complete Boolean This indicates that the goal has been completed.
meta_type String The meta type of the goal; see goal meta types below for more information.
metadata String Additional information a partner can store on the goal.
name String The name of the goal.
position Integer The priority position of the goal in relation to multiple goals.
projected_to_complete_at Integer The date and time the goal is projected to be completed.
revision Integer The revision number of the goal record.
updated_at Integer The date and time this goal was last updated.
user_guid String The unique identifier for the user the goal is associated with. Defined by MX.
user_id String The unique, partner-defined identifier for the user the goal is associated with.

Goal Meta Types

Meta type
AUTOMOBILE
COLLEGE
ELECTRONIC
EMERGENCY_FUND
HOUSE
OTHER
RECREATIONAL_VEHICLE
RETIREMENT
SETUP_BUDGETS
START_MONEY_MANAGEMENT
VACATION

Holdings

Holdings represent a stock, bond, or other type of investment, as found in the following MX products (some links point to an external MX site):

Holding Fields

Field name Data type Definition
account_guid String The unique identifier for the account associated with the holding. Defined by MX.
bond_coupon_rate Decimal The coupon rate for a bond.
bond_maturity_date Integer The date and time a bond matures.
classification String An alias for the field equity_classification.
cost_basis Decimal The cost basis is the original value of an asset adjusted for stock splits, dividends, and capital distributions.
created_at Integer The date and time the holding was created.
cusip String The Committee on Uniform Securities Identification Procedures (CUSIP) code; an identification number assigned to stocks and registered bonds.
daily_change Decimal The change from the previous day in the price of the holding.
deleted_at Integer The date and time the holding was deleted.
description String The description of the holding after being cleansed by MX into a human-readable format.
equity_classification String The equity classification of the holding. See the section on equity classifications below for more information.
fixed_income_classification String A graphical representation of the investment style of the fixed income funds within a holding (like bonds) according to the Morningstar Style Box. See the section on fixed income classifications for more information.
guid String The unique identifier for the holding. Defined by MX.
holding_type String The type of holding, e.g., mutual fund, bond, etc. See the section on holding types below for more information.
id String The unique identifier for the holding. Defined by the data provider.
is_deleted Boolean This indicates that the holding has been deleted.
isin String The International Securities Identification Number (ISIN) in ISO 6166 format.
market_value Decimal The market value of the holding.
member_is_managed_by_user Boolean This indicates that the member associated with the holding is managed by the user.
metadata String Additional information a partner can store on the holding.
purchase_price Decimal The purchase price of the holding.
revision Integer The revision number of the holding record.
sector String The area of the economy the holding is invested in. See the section on sectors for more information.
sedol String The Stock Exchange Daily Official List (SEDOL) classification code, represented as a seven-character code (e.g. B03MM40).
shares Decimal The number of shares owned for the holding.
symbol String The ticker symbol, i.e. the abbreviation used to uniquely identify publicly traded stocks, bonds, mutual funds, and ETFs.
updated_at Integer The date and time the holding was last updated.
user_guid String The unique identifier for the user the holding is associated with. Defined by MX.
user_id String The unique identifier for the user the holding is associated with. Defined by the partner.

Equity Classifications

Equity classifications
UNKNOWN
LARGE_VALUE
LARGE_CORE
LARGE_GROWTH
MID_VALUE
MID_CORE
MID_GROWTH
SMALL_VALUE
SMALL_CORE
SMALL_GROWTH

Fixed Income Classifications

Fixed income classifications
UNKNOWN_FIXED_INCOME_CLASSIFICATION
HIGH_LIMITED
HIGH_MODERATE
HIGH_EXTENSIVE
MEDIUM_LIMITED
MEDIUM_MODERATE
MEDIUM_EXTENSIVE
LOW_LIMITED
LOW_MODERATE
LOW_EXTENSIVE

Sectors

Sectors
UNKNOWN_SECTOR
BASIC_MATERIALS
CONSUMER_CYCLICAL
FINANCIAL_SERVICES
REAL_ESTATE
CONSUMER_DEFENSIVE
HEALTHCARE
UTILITIES
COMMUNICATION_SERVICES
ENERGY
INDUSTRIALS
TECHNOLOGY

Holding Types

Types
UNKNOWN_TYPE
EQUITY
EXCHANGE_TRADED_FUND
MONEY_MARKET
MUTUAL_FUND
HEDGE_FUND
ANNUITY
UNIT_INVESTMENT_TRUST
CASH
FIXED_INCOME
OPTIONS

Members

A member represents the relationship between a user and an institution. A user may have multiple members, one each for their bank, their mortgage broker, their credit card provider, etc. Aggregation, verification, and many other processes are centered around a member. Daily change files reflect member changes resulting from background aggregation as well as from the following MX products (some links point to an external MX documentation site):

Member Fields

Field Name Data Type Definition
connection_status_id Integer This indicates the state of a member’s aggregation. See the section on member connection statuses below for more information on possible values. This field will reflect the value as of the time that the daily files were generated, which is around midnight UTC. If partners need to know the connection status in real-time, they should use the Nexus or Platform API’s read member endpoints to retrieve the information, or subscribe to the connection status webhook.
connection_status_message String A message that can be displayed to the user to help them navigate the connection and aggregation process.
connection_status String This indicates the state of a member’s aggregation. See the section on member connection statuses below for more information on possible values. This field will reflect the value as of the time that the daily files were generated, which is around midnight UTC. If partners need to know the connection status in real-time, they should use the Nexus or Platform API’s read member endpoints to retrieve the information, or subscribe to the connection status webhook.
created_at Integer The date and time the member was created.
guid String The unique identifier for the member. Defined by MX.
id String The partner-defined unique identifier for the member.
institution_guid String The unique identifier for the institution associated with the member. Defined by MX.
institution_id String An alternate unique identifier for the member’s institution. Defined by MX.
is_managed_by_user Boolean This indicates that the member is managed by the user.
is_manual Boolean This indicates that the member was created manually.
is_user_created (deprecated) Boolean If the member was created by the user, this field will be true. Otherwise, this field will be false. The field is_user_created has been deprecated. Partners should use the field is_managed_by_user instead. Both fields are included for backward compatibility.
metadata String Additional information a partner can store on the member.
name String The name of the member.
revision Integer The revision number of this member record.
successfully_aggregated_at Integer The date and time this member was last successfully aggregated.
updated_at Integer The date and time this member was last updated.
user_guid String The unique identifier for the user associated with the member. Defined by MX.
user_id String The unique partner-defined identifier for the user associated with the member.

Member Connection Statuses

Integer Value Status Definition Next Steps End-User Message
null null The member exists but does not have credentials. A member that does not aggregate (e.g., a manual member) will always have this status. None. None.
0 CREATED The member is new and has not yet been aggregated. Aggregate the member once the end user logs in; poll for a status update. Connecting to {…} …
1 PREVENTED MX is preventing aggregation until the member’s credentials have been updated. Display end-user message; after end user has updated their credentials, aggregate again. The last 3 attempts to connect have failed. Please re-enter your credentials to continue importing data.
2 DENIED The credentials provided for the member were invalid. Display end-user message; after end user has updated their credentials, aggregate again. The credentials entered do not match your credentials at this institution. Please re-enter your credentials to continue importing data.
3 CHALLENGED The member has been challenged by multi-factor authentication. Display end-user message; follow MFA pathway; after the user answers MFA, poll for a status update. To authenticate your connection to {…}, please answer the following challenge(s).
4 REJECTED An MFA challenge was answered incorrectly. Display end-user message; another challenge may follow or aggregation may need to be restarted. The answer or answers provided were incorrect. Please try again.
5 LOCKED The financial institution is preventing authentication. The end user must contact the financial institution. Display end-user message. Your account is locked. Please log in to the appropriate website for {…} and follow the steps to resolve the issue.
6 CONNECTED The member was successfully authenticated and data is now aggregating. Display the account as having been connected. Connected to […] …
7 IMPEDED The end user’s attention is required at their online banking institution, e.g., there is a marketing message that must be viewed, terms and conditions that must be accepted, etc. Display end-user message. Your attention is needed at this institution’s website. Please log in to the appropriate website for {…} and follow the steps to resolve the issue.
8 RECONNECTED The member has been migrated to a new data source and aggregation is likely to trigger one-time password MFA. MX will not perform background aggregation in order to avoid unnecessarily disruptive texts, emails, etc. The member must be re-aggregated in the foreground with the end user present. Aggregate the member once the end user logs in; poll for a status update. Reconnecting to {…} …
9 DEGRADED Aggregation has failed at least three times within a short period of time. Display end-user message. We are upgrading this connection. Please try again later.
10 DISCONNECTED Aggregation has failed at least three times and has not succeeded for at least two weeks. Display end-user message. It looks like your data from {…} cannot be imported. We are working to resolve the issue.
11 DISCONTINUED The connection to this financial institution is no longer available. Display end-user message. Connections to this institution are no longer supported. You may create a manual account and use manual transactions to track data for this account.
12 CLOSED The end user, MX, the client, or a partner has marked the member as closed. Display end-user message. This connection has been closed. You may track this account manually. If reopened, you may connect the institution again.
13 DELAYED Aggregating the member has taken longer than expected and it has not yet been connected. Display end-user message; poll for a status update. Importing your data from {…} may take a while. Please check back later.
14 FAILED Aggregation failed without being connected. Display end-user message; try aggregating again later. There was a problem validating your credentials with {…}. Please try again later.
15 UPDATED The member has been updated — i.e., credentials have been updated — but it has not yet been connected. Aggregate the member once the end user logs in; poll for a status update. Connecting to {…} …
16 DISABLED Aggregation has been momentarily paused, but the member is still connected. Display end-user message. Importing data from this institution has been disabled. Please contact us if you believe it has been disabled in error.
17 IMPORTED MX does not have credentials and will not try to aggregate the member until the end user provides credentials. Display end-user message; re-aggregate after the end user updates credentials. You must re-authenticate before your data can be imported. Please enter your credentials for {…}.
18 RESUMED The answer to an MFA challenge was received, but it is not yet clear whether it was correct. Poll for a status update. Connecting to {…} …
19 EXPIRED The MFA answer was not provided within the time allotted by the financial institution. Display end-user message; re-aggregate the member if the end user initiates it. The answer or answers were not provided in time. Please try again.
20 IMPAIRED The member is missing some or all credentials needed in order to connect. Display end-user message; re-aggregate after the end user updates credentials. You must re-authenticate before your data can be imported. Please enter your credentials for {…}.
21 PENDING The member is using OAuth to authenticate credentials and still needs to go through the financial institution’s OAuth process. A PENDING status will appear only on members less than one hour old with is_oauth: true. Members that stay PENDING longer than one hour will be deleted by MX. Redirect the end user to the oauth_window_uri provided in the create member response, or request one through the generate OAuth window URI endpoint. None.

Notification Profiles

Notification profiles are related to MX’s MoneyMap widgets (link points to an external MX documentation site).

Notification Profile Fields

Field Data type Definition
created_at Integer The date and time at which the notification profile was created.
email_channel Boolean This indicates whether email notifications are enabled for the user.
entity_guid String The unique identifier for the object associated with this notification, e.g., BGT-1234 or TRN-2345.
guid String The unique identifier for the notification profile. Defined by MX.
is_enabled Boolean This indicates whether notifications are enabled for the user.
last_recorded_at Integer The date and time a notification of a given type was last triggered.
notification_type String The type of notification, e.g., BUDGET_EXCEEDED or OFFER.
push_channel Boolean This indicates whether push notifications are enabled for the user.
scheduled_for Integer For recurring notification types such as DEBT_PAYMENT_REMINDER, this is the date and time the next notification is scheduled to be delivered.
sms_channel Boolean This indicates whether SMS notifications are enabled for the user.
threshold Integer This is the monetary threshold that will trigger a notification for certain notification types, such as BUDGET_EXCEEDED.
updated_at Integer The time at which the notification profile was last updated.
user_guid String The unique identifier for the user associated with the notification profile. Defined by MX.
user_id String The partner-defined unique identifier for the user associated with the notification profile.

Notification Types

Type integer Type string
1 BUDGET_EXCEEDED
2 BUDGET_OFF_TARGET
3 DEBT_PAYMENT_REMINDER
4 (deprecated) GUIDE_ME_STEP_COMPLETE
5 (deprecated) GUIDE_ME_OFF_TARGET
6 ACCOUNT_BALANCE_LOW
7 ACCOUNT_DEPOSIT_LARGE
8 TRANSACTION_EXPENSE_LARGE
9 TRANSACTION_FEE_CHARGE
10 (deprecated) SYSTEM_NOTIFICATION
11 API_NOTIFICATION
12 USER_SUMMARY
13 OFFER
14 PASSWORD_RESET_TOKEN
15 PASSWORD_CHANGED
16 EMAIL_VERIFICATION
17 EMAIL_VERIFIED
18 WELCOME_NEW_USER
19 DEVICE_CREATED
20 DEVICE_DELETED
21 SMS_VERIFICATION
22 ACCOUNT_NEARING_ZERO
23 TRANSACTION_IS_INTERNATIONAL
24 INVALID_CONTACT_INFORMATION
25 GOAL_PROGRESS
26 CREATE_GOAL
27 FORGOT_USERNAME_REMINDER
28 SMS_WELCOME_MESSAGE
29 DUPLICATE_PAYMENT

Taggings

Taggings represent the association of a tag to a transaction. In other words, with a tagging, a transaction can be assigned a specific tag, either the default business tag, or any other user-created tag. Daily files represent changes resulting from the following MX products (some links point to an external MX documentation site):

Tagging Fields

Field name Data type Definition
guid String The unique identifier for the tagging. Defined by MX.
member_is_managed_by_user Boolean This indicates that the member the associated with the tagging is managed by the user.
revision Integer The revision number of the tagging record.
transaction_guid String The unique identifier for the transaction associated with the tag. Defined by MX.
transaction_id String The partner-defined unique identifier for the transaction associated with the tag. Defined by the data provider.
tag_guid String The unique identifier for the tag. Defined by MX.
tag_name String The name of the tag.
updated_at Integer The date and time the tag was last updated.
user_guid String The unique identifier for the user the tag is associated with. Defined by MX.
user_id String The partner-defined unique identifier for the user associated with the tag.

Tags

Tags allow partners and end users to create a custom label for particular transactions. Daily files represent changes resulting from the following MX products (some links point to an external MX documentation site):

Tag Fields

Field name Data type Definition
guid String The unique identifier for the tag. Defined by MX.
name String The name of them tag.
revision integer The revision number of the tag record.
updated_at integer The date and time the tag was last updated.
user_guid String The unique identifier for the user the tag is associated with. Defined by MX.
user_id String The unique partner-defined identifier for the user associated with the tag.

Transactions

A transaction represents any instance in which money moves into or out of an account, such as a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, etc. Each transaction belongs to only one account. Daily files represent changes resulting from background aggregation as well as the following MX products (some links point to an external MX documentation site):

Transaction Fields

Field name Data type Definition
account_guid String The unique identifier for the account associated with this transaction. Defined by MX.
account_id String The unique partner-defined identifier for the account associated with the transaction.
amount Decimal The monetary amount of the transaction.
category_guid String The unique identifier for the category assigned to the transaction.
category String The category of the transaction.
check_number (deprecated) Integer The check number for the transaction. This field will be null if the value is not an Integer, or if its value is too large to fit in a long object type. This filed has been deprecated; partners should use check_number_String instead.
check_number_string String The check number for the transaction.
created_at String The date and time the transaction was created.
date Integer The date on which the transaction took place. This is the field used when searching for transactions by date. This field is generally the same as transacted_at, but uses posted_at as a fallback.
description String A human-readable version of the feed_description field described below, e.g., “Sam’s Club,” “Johnny’s Tavern.” This is provided by the MX Platform.
feed_description String The original description of the transaction as provided by our data feed. See description above for more information.
feed_localized_description String The original description of the transaction as provided by our data feed, given in a local language. See description above for more information.
feed_localized_memo String Additional descriptive information about the transaction as provided by our data feed, given in a local language.
feed_transaction_type String The type of the transaction, as provided by our data feed. See type for more information.
guid String The unique identifier for the transaction. Defined by MX.
has_been_split Boolean This indicates whether the transaction has been split.
has_been_viewed Boolean This indicates whether the transaction has been viewed.
id String The unique partner-defined identifier for the transaction.
is_bill_pay Boolean This indicates whether the transaction represents a bill pay.
is_direct_deposit Boolean This indicates whether the transaction represents a direct deposit.
is_expense Boolean This indicates whether the transaction represents an expense.
is_fee Boolean This indicates whether the transaction represents a fee.
is_flagged Boolean This indicates whether the transaction has been flagged.
is_hidden Boolean This indicates whether the transaction is hidden.
is_income Boolean This indicates whether the transaction represents income.
is_international Boolean If the transaction is international, as defined by the data provider, this field will be true. If the data provider determines it is not international then it will be false. It will be null if the data provider does not provide this information.
is_overdraft_fee Boolean This indicates whether the transaction represents an overdraft fee.
is_payroll_advance Boolean This indicates whether the transaction represents a payroll advance.
is_personal Boolean This indicates whether the transaction has been marked as personal by the user.
is_recurring Boolean This indicates whether the transaction represents a recurring credit or debit.
is_subscription Boolean This indicates whether the transaction represents a payment for a subscription service such as Netflix or Audible.
latitude Decimal The latitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro’s latitude is -22.9027800 and Tokyo’s latitude is 35.689488).
localized_description String A human-readable description of the transaction, provided in a local language.
localized_memo String Additional descriptive information about the transaction, provided in a local language.
longitude Decimal The longitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro’s longitude is -43.2075000 and Tokyo’s longitude is 139.691706).
member_is_managed_by_user Boolean This indicates whether the associated member is managed by the user or the MX partner.
memo String This field contains additional descriptive information about the transaction.
merchant_category_code Integer The ISO 18245 category code for the transaction.
metadata String Additional information a partner can store on the transaction.
parent_guid String The unique identifier for the parent transaction associated with a split transaction. Defined by MX.
posted_at String The date and time the transaction was posted to the account.
posted_on String The date the transaction was posted to the account.
revision Integer The revision number of the transaction record.
status String The status of the transaction. This will be either POSTED or PENDING.
top_level_category_guid String The unique identifier for the parent category assigned to this transaction’s category. Defined by MX.
transacted_at String The date and time the transaction took place.
transacted_on String The date the transaction took place.
type String The type of transaction. This will be either CREDIT or DEBIT.
updated_at String The date and time the transaction was last updated.
user_guid String The unique identifier for the user associated with the transaction. Defined by MX.
user_id String The unique partner-defined identifier for the user associated with the transaction.

Users

A user represents an end-user accessing the MX Platform API via your application, be it a mobile app, web app, desktop app, etc.

Daily files represent changes resulting the following MX products (some links point to an external MX documentation site):

Field name Data type Definition
birthdate String The birthdate of end user.
birthday String An alias for the birthdate field.
created_at Integer The date and time the user was created.
email String The end user’s email address.
email_is_verified Boolean This indicates whether the end user has verified their email.
first_name String The first name of the end user.
gender String The gender of the end user. Returns either MALE, FEMALE or null.
guid String The unique identifier for the user. Defined by MX.
id String A unique, partner-defined, enforced identifier for the user.
is_disabled Boolean This indicates whether the user has been disabled through the API.
last_name String The last name of the end user.
logged_in_at Integer The date and time the end user last logged in.
metadata String Additional information a partner can store on the user.
phone String The phone number of the end user.
phone_is_verified Boolean this indicates whether the end user has verified their phone number.
postal_code String An alias for the zip_code field.
revision Integer The revision number of the user record.
updated_at Integer The date and time the user was last updated.
zip_code String The US zip code or Canadian postal code of the end user.

Analytics Events

Analytics events cover a range of things related to both the MoneyMap widgets and the Helios mobile app. Not all the analytics files will have data in them depending on whether partners are using MoneyMap, Helios, or both. For example, partners using MoneyMap widgets only (whether on desktop or mobile) will have data in analytics events files and analytics pageviews files, but not analytics screenviews nor analytics timed events.

Resource Data Source Description
analytics_events MoneyMap and Helios Analytics events occur within a MoneyMap widget (desktop or mobile) or a Helios mobile view.
analytics_pageviews MoneyMap Opening various widgets or tabs within master widget.
analytics_screenviews Helios Opening various views or screens within Helios app.
analytics_timed_events Helios Measures the timing of different events within Helios app.

Analytics Events

Analytics events occur within a MoneyMap widget (desktop or mobile) or a Helios mobile view.

Analytics Event Fields

Field name Data type Definition
action String The action by the end user that triggered the analytics event (e.g. blur, click, etc.).
app_guid String The unique identifier for the app based on the client and operating system (e.g., Epic Bank iOS and Epic Bank Android would have separate identifiers). Defined by MX. If the data_source is web, this field will be null.
app_version String The specific version of the application with which the end user interacted.
category String The category or feature with which the user interacted (e.g., Add Manual Account, Credential Login, etc.).
client_guid String The unique identifier for the client associated with this analytics event. Defined by MX.
created_at Integer The date and time this analytics event was created. Represented as a Unix Epoch datetime (e.g. 1489883830).
data_source String The origin of the analytics event (e.g., web for web application or app for mobile application).
device_guid String The unique identifier for the device associated with the analytics event. Defined by MX. If the data_source is web, this field will be null.
device_id String The unique identifier for the device associated with the analytics event; resets on every login. Defined by MX.
device_uid String The unique identifier for the device associated with the analytics event; remains constant across logins. Defined by MX.
external_user_guid String The partner-defined identifier for the user associated with the event.
guid String The unique identifier for the analytics event. Defined by MX.
is_mobile_webview Boolean The widget configuration as it was set at the time of the API request to obtain the widget.
mdx_session_id String The hashed MDX session ID, provided as a custom dimension.
name String The name of the action taken that generated the analytics event (e.g., Account Type - Collapse, Exclude Transaction - Start, etc.).
screen_resolution String The resolution of the device display associated with the analytics event, given in pixels (e.g., 2048x1536).
session_id String The unique identifier of the session, provided as a custom dimension.
user_agent String The end user’s browser and operating system.
user_guid String The unique identifier for the user associated with the analytics event. Defined by MX.
user_id String The partner-defined identifier for the user associated with the event.
user_ip_address String The unique IP address for the user associated with the analytics event.
value String The screen object the user interacted with, if applicable (e.g., Button, Menu, Previous Month).

Analytics Pageviews

Analytics pageviews include pageviews only for the MoneyMap widgets.

Analytics Pageview Fields

Field name Data type Definition
app_version String The version of the user’s application.
client_guid String The unique identifier for the client associated with the analytics pageview. Defined by MX.
created_at Integer The date and time at which the analytics pageview was created.
data_source String The origin of the analytics event, e.g. transactions for the transactions widget, master/transactions if the master widget is loaded, app for mobile application.
external_user_guid String The partner-defined identifier for the user associated with the pageview.
guid String The unique identifier for the analytics pageview. Defined by MX.
host String The host name of the server.
is_mobile_webview Boolean The widget configuration as it was set at the time of the API request to obtain the widget.
name String The name of the page in the case of a pageview.
path String The relative URL path of the event.
screen_resolution String The resolution of the device display associated with the analytics event; given in pixels (e.g. 2048x1536).
session_id String The unique identifier of the session, provided as a custom dimension.
user_agent String The end user’s browser and operating system.
user_guid String The unique identifier for the user associated with the analytics pageview. Defined by MX.
user_id String The partner-defined identifier for the user associated with the pageview.
user_ip_address String The IP address of the user associated with this analytics pageview.

Analytics Screenviews

Analytics screenviews include screenviews only for the Helios mobile app.

Analytics Screenview Fields

Field Name Data Type Definition
app_guid String The unique identifier for the app based on the client and operating system (e.g., Epic Bank iOS and Epic Bank Android would have separate identifiers). Defined by MX. If the data_source is web, this field will be null.
app_version String The specific version of the application with which the end user interacted.
client_guid String The unique identifier for the client associated with this analytics screenview. Defined by MX.
created_at Integer The date and time the analytics screenview was created, given in Unix epoch time.
data_source String The origin of the analytics screenview (e.g., web for web application or app for mobile application).
device_guid String The unique identifier for the device associated with the analytics screenview. Defined by MX. If the data_source is web, this field will be null.
device_id String The unique identifier for the device associated with the analytics screenview; resets on every login. Defined by MX.
device_uid String The unique identifier for the device associated with the analytics screenview; remains constant across logins. Defined by MX.
external_user_guid String The partner-defined identifier for the user associated with the screenview.
guid String The unique identifier for the analytics screenview. Defined by MX.
mdx_session_id String The hashed MDX session ID, provided as as custom dimension.
name String The name of the action taken in the analytics screenview.
screen_resolution String The resolution of the device display associated with the analytics screenview; given in pixels (e.g., 2048x1536).
session_id String The unique identifier of the session, provided as a custom dimension.
user_agent String The end user’s browser and operating system.
user_guid String The unique identifier for the user associated with the analytics screenview. Defined by MX.
user_id String The partner-defined identifier for the user associated with the screenview.
user_ip_address String The IP address of the user associated with this analytics pageview.

Analytics Timed Events

Analytics timed events measure the timing of different events within Helios mobile app.

** Analytics Timed Event Fields**

Field Data type Definition
app_guid String The unique identifier for the app based on the client and OS (e.g. Epic Bank iOS and Epic Bank Android would have separate identifiers). Defined by MX. If the data_source is web, this field will be null.
app_version String The version of the user’s application.
category String The category or feature with which the user interacted (e.g. Add Manual Account, Credential Login, etc.).
client_guid String The unique identifier for the client associated with this analytics event. Defined by MX.
created_at Integer The date and time at which the analytics timed event was created.
data_source String The origin of the analytics event (e.g. web for web application or app for mobile application).
device_guid String The unique identifier for the device associated with the analytics event. Defined by MX. If the data_source is web, this field will be null.
device_id String The unique identifier for the device associated with the analytics event; resets on every login. Defined by MX.
device_uid String The unique identifier for the device associated with the analytics event; remains constant across logins. Defined by MX.
external_user_guid String The partner-defined identifier for the user associated with the pageview.
guid String The unique identifier for the analytics timed event. Defined by MX.
interval Integer The duration of the analytics timed event from start to finish, given in milliseconds.
mdx_session_id String The hashed MDX session ID, provided as a custom dimension.
name String The name of the action taken which generated the analytics event (e.g. Account Type - Collapse, Exclude Transaction - Start, etc.).
screen_resolution String The resolution of the device display associated with the analytics event; given in pixels (e.g. 2048x1536).
session_id String The unique identifier of the session, provided as a custom dimension.
user_agent String The end user’s browser and operating system.
user_guid String The unique identifier for the user associated with the analytics timed event. Defined by MX.
user_id String The partner-defined identifier for the user associated with the pageview.
user_ip_address String The unique IP address for the user associated with the analytics event.
version Integer The version of the user’s application, given as an integer.

Discovered Accounts


Discovered Accounts

Field name Data type Definition
client_guid String The unique identifier for the client associated with the discovered account. Defined by MX.
created_at Integer The date and time at which the discovered account was created.
deleted_at Integer The date and time at which the discovered account was deleted.
guid String The unique identifier for the discovered account. Defined by MX.
has_been_aggregated Boolean This indicates whether the discovered account has been aggregated at some point by MX systems.
is_deleted Boolean This indicates whether the discovered account has been deleted on MX systems.
most_recent_transaction_amount Decimal The amount of the most recent known transaction for the discovered account.
most_recent_transaction_date Integer The date and time of the most recent known transaction for the discovered account.
most_recent_transaction_guid String The unique identifier for the most recent known transaction associated with the discovered account. Defined by MX.
name String The name of the discovered account.
organization_guid String The unique identifier for the organization associated with the discovered account. Defined by MX.
potentially_carries_a_balance Boolean This indicates that the discovered account may carry a balance, based on the information available to MX.
sub_type String The discovered account’s subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY.
type String The general or parent type of the discovered account.
updated_at Integer The date and time the account was last updated.
user_guid String The unique identifier for the user associated with the discovered account. Defined by MX.
user_id String The unique, partner-defined identifier for the user associated with the discovered account.

Discovered Transactions

Field name Data type Definition
amount Decimal The amount of the discovered transaction.
created_at Integer The date and time at which the discovered transaction was created.
date Integer The date on which the discovered transaction occurred, given in unix time.
discovered_account_guid String The unique identifier for the discovered account associated with the discovered transaction. Defined by MX.
discovered_account_subtype String The subtype of the discovered account associated with discovered transaction, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY.
discovered_account_type String The general or parent type of the discovered account associated with the discovered transaction.
guid String The unique identifier for the discovered transaction. Defined by MX.
has_been_aggregated Boolean This indicates whether the transaction has been aggregated by MX systems.
id String The unique, partner-defined identifier for the discovered transaction.
organization_guid String The unique identifier for the organization associated with the discovered transaction. Defined by MX.
posted_at Integer The date and time at which the transaction was marked as posted.
transacted_at Integer The date and time at which the transaction occurred.
updated_at Integer The date and time at which the transaction was last updated.
user_guid String The unique identifier for the user associated with the discovered transaction. Defined by MX.
user_id String The unique, partner-defined identifier for the user associated with the discovered transaction.

User Communication


User Communications Profiles

User communication profiles are related to MX’s MoneyMap widgets (link points to an external MX documentation site).

User Communication Profile Fields

Field name Data type Definition
created_at Integer The date and time the user communications profile was created.
guid String The unique identifier for the user communications profile. Defined by MX.
opted_out_of_all_notifications Boolean This indicates whether the user has opted out of all notifications. Defaults to false.
opted_out_of_all_notifications_updated_at Integer The date and time this user opted out of all notifications.
opted_out_of_email_notifications Boolean This indicates whether the user has opted out of email notifications. Defaults to false.
opted_out_of_email_notifications_updated_at Integer The date and time this user opted out of email notifications.
opted_out_of_push_notifications Boolean This indicates whether the user has opted out of push notifications. Defaults to true.
opted_out_of_push_notifications_updated_at Integer The date and time this user opted out of push notifications.
opted_out_of_sms_notifications Boolean This indicates whether the user has opted out of SMS notifications. Defaults to false.
opted_out_of_sms_notifications_updated_at Integer The date and time this user opted out of SMS notifications.
user_guid String The unique identifier for the user associated with the user communication profile. Defined by MX.

Download Daily Files

The Reporting API provides reports of any create, update or delete events that took place on a particular date for each available resource_type. There is a specific endpoint for each action that took place for the resource on that specific day.

If a particular resource has no data for a given day, a file with headers but no body will be generated and made available for retrieval.

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.

If a file being requested is no longer available, a 410 Gone status will be returned.

URL parameters

Parameter Description
date The date of the file being requested.
resource_type This must be one of the following resource types. See the data specs above for more information on each resource.

accounts
analytics_events
analytics_pageviews
analytics_screenviews
analytics_timed_events
beat
beat_feedback
budgets
categories
devices
discovered_accounts
discovered_transactions
goals
holdings
members
notification_profiles
tags
taggings
transactions
user_communication_profiles
users
action This must be one of the following action types:

created
updated
deleted

Endpoint structure:

GET /download/:date/:resource_type/:action

Example URLs:

GET https://int-logs.moneydesktop.com/download/ABC-Bank/2017-06-26/transactions/created

GET https://int-logs.moneydesktop.com/download/MyFirstCU/2017-06-26/accounts/updated

GET https://int-logs.moneydesktop.com/download/XYZBank/2017-06-26/members/deleted
1
2
3
4
5
6
7
8
# If using curl, the output response can be saved
# to a file by adding the `-o` flag and
# specifying the download path and file name
# (e.g. `-o 20170626-transactions-created.avro`).

curl -X GET https://int-logs.moneydesktop.com/download/{client_id}/2017-06-26/transactions/created -o 20170626-transactions-created.avro \
  -H 'Accept: application/vnd.mx.logs.v1+avro' \
  -H 'MD-API-KEY: {api_key}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;

public class Reporting_API {
    private String BaseUrl, ClientId, ApiKey;

    public Reporting_API(String BaseUrl, String ClientId, String ApiKey) {
        this.BaseUrl = BaseUrl;
        this.ClientId = ClientId;
        this.ApiKey = ApiKey;
    }

    public static void main(String[] args) throws Exception {
        String base_url = "https://int-logs.moneydesktop.com";
        String client_id = ":client_id";
        String api_key = ":api_key";

        Reporting_API reporting = new Reporting_API(base_url, client_id, api_key);

        /// Setup IDs
        String date = "2017-07-27";
        String resource_type = "transactions";
        String action_type = "created";

        reporting.Download(date, resource_type, action_type);
    }

    public void Download(String date, String resource_type, String action_type) {
        try {
            String uri = BaseUrl + "/download/" + ClientId + "/" + date + "/" + resource_type + "/" + action_type;
            URL url = new URL(uri);

            HttpsURLConnection con = (HttpsURLConnection) url.openConnection();
            con.setRequestMethod("GET");
            con.setRequestProperty("Accept", "application/vnd.mx.logs.v1+avro");
            con.setRequestProperty("MD-API-KEY", ApiKey);

            BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            con.disconnect();

            System.out.println(response.toString());
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
from httplib import HTTPSConnection
import json

BASE_URL = "int-logs.moneydesktop.com"
CLIENT_ID = ":client_id"
API_KEY = ":api_key"
ACCEPT = "application/vnd.mx.logs.v1+avro"

class Reporting_API:
    def __init__(self, base_url, client_id, api_key):
        self.base_url = base_url
        self.client_id = client_id
        self.api_key = api_key
    def Download(self, date, resource_type, action_type):
        request_uri = "/download/" + self.client_id + "/" + date + "/" + resource_type + "/" + action_type
        conn = HTTPSConnection(self.base_url)
        headers = { "MD-API-Key" : self.api_key, "Accept" : ACCEPT }
        conn.request("GET", request_uri, "", headers)
        response = conn.getresponse()
        return response.read()

reporting = Reporting_API(BASE_URL, CLIENT_ID, API_KEY)

date = "2017-07-26"
resource_type = "transactions"
action_type = "created"

response = reporting.Download(date, resource_type, action_type)
print response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
require "json"
require "net/http"

module Reporting_API
  def Reporting_API.download(options)
    uri = URI(options[:host])
    uri.path << "/download/#{options[:client_id]}/#{options[:date]}/#{options[:resource_type]}/#{options[:action_type]}"

    request = ::Net::HTTP::Get.new(uri)
    request["Accept"] = "application/vnd.mx.logs.v1+avro"
    request["MD-API-KEY"] = options[:api_key]
    request.body = options[:body]

    response = ::Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
      http.request(request)
    end

    case response
    when ::Net::HTTPSuccess
      puts "[SUCCESS] [#{response.code}] #{response.body}"
    else
      puts "[FAILURE] [#{response.code}] #{request.body}"
    end
  end
end

Reporting_API.download(
  :host => "https://int-logs.moneydesktop.com",
  :api_key => ":api_key",
  :client_id => ":client_id",
  :date => "2017-07-26",
  :resource_type => "transactions",
  :action_type => "created"
)

Snapshots

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

MX must generate the snapshot before it can be downloaded. This process can take several days depending on the amount of data on the platform. In order to keep file sizes reasonable for downloading, multiple files may be generated for each resource. Once snapshots have been generated, MX will provide the partner with a GUID which can be used to download the snapshot files.

The response will be in an Avro file format with gzip compression. Files can be saved with .gz extension and then unpacked using gunzip.

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.

MX will retain snapshot files long enough for a partner to retrieve them; however, these files will not remain available long-term. Once a partner has verified that the files have been retrieved, MX will remove the files from storage. It is the partner’s responsibility to download and retain the files in their own system.

MX will generate snapshots for the following resources:

  • Accounts
  • Devices
  • Goals
  • Members
  • Notification profiles
  • Transactions
  • Users

Download Snapshots

The URLs returned in the list snapshot file URLs endpoint should be used to download each file individually.

Endpoint:

GET /snapshot/{client_id}/{snapshot_guid}/{file_name}

1
2
3
4
5
6
7
8
# If using curl, the output response can be saved
# to a file by adding the flag option `-o` and specifying
# the download path and file name
# (e.g. `-o transactions-snapshot.avro.gz`).

curl -X GET https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/transactions_cf3586e2a0eeb0049f7074926076acfe -o filename.avro.gz \
  -H 'Accept: application/vnd.mx.logs.v1+avro' \
  -H 'MD-API-KEY: {api_key}'

List Snapshot File URLs

This endpoint returns a JSON array of snapshot file URLs.

Endpoint:

GET /snapshot/{client_id}/{snapshot_guid}/files

1
2
3
curl -i -X GET https://int-logs.moneydesktop.com/snapshot/:client_id/:snapshot_guid/files.json \
  -H 'Accept: application/vnd.mx.logs.v1+json' \
  -H 'MD-API-KEY: :api_key'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
   "transactions":[
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/transactions_cf3586e2a0eeb0049f7074926076acfe",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/transactions_b251482912c96f0b6158ca3f280aa439",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/transactions_89535caacfb7e6ea1e95c3a2dbb294cd"
   ],
   "users":[
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/users_40ace30a4502ebe473a6ad10988cde85",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/users_63ef78664a12fd6c738e7d9d2af9c33d",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/users_18c75f36b3d467a2ca6f5c594797a8d0"
   ],
   "devices":[
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/devices_49c6b1bba54ec84ed722f803776e1311",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/devices_f354abfb9c0476282da85e876faf10a3",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/devices_3f3eb57fcc2f7b0d3b02a617739c6e32"
   ],
   "accounts":[
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/accounts_6d660749330ba2cb4da17dd57cc668ff",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/accounts_384051b5b84463a4e2157bb351ed4eec",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/accounts_75be26f6e316a73853eed9fd3182c658"
   ],
   "members":[
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/members_df8c4ae1f900cb714a099bedc5c7f382",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/members_21904fcdacc194d840dd83851e145ab1",
      "https://int-logs.moneydesktop.com/snapshot/ABCBank/CSS-2f5fcc32-2505-41c2-b04e-11a15c4dc37/members_720266a2a12722ee2e1e7dbf601779e5"
   ]
}

SFTP Delivery

Partners may optionally have MX deliver their daily reporting files to an SFTP server rather than retrieving them through the API endpoints. In order to do so, there are certain requirements.

  • Partners must provide an SFTP server
  • Partners must provide a public GPG key
  • SFTP server must use a non-standard port, i.e., not port 22
  • Partners must provide a username and password to MX for authentication to the SFTP server
  • MX will need to whitelist any IP addresses for the partner’s SFTP server

If a particular resource has no data for a given day, an Avro file with headers but no body will still be generated and delivered.


Daily Files Manifest

Partners who use SFTP will also be sent an encrypted manifest file in CSV format containing information about each daily file being delivered. This includes the resource type, the event type (created, updated, etc.), the date, number of records, and file size. Each row in the manifest file represents one daily file in the bunch.

Each manifest file will be named according to the following format: client_guid.snapshot_date-manifest.csv.pgp.

Manifest files are encrypted using the same public key as the daily files.

Manifest file fields

Field name Data type Definition
Checksum String The SHA-256 hash value of the daily file.
EffectiveDate String The date for which the daily file was generated, given in ISO 8601 format with a timestamp.
EncryptedFileSize Integer The size of the encrypted daily file in bytes.
EventType String The action for the given resource, i.e., created, updated, deleted.
FileName String The name of the daily file without file extension.
FileSize Integer The size of the daily file in bytes.
RecordCount Integer The number of records in the daily file.
ResourceType String The type of resource for the daily file, e.g. accounts, analytics events, budgets, etc.

Resource types

New resource types may be added at any time.

Resource type string
ACCOUNTS
ANALYTICS_EVENTS
ANALYTICS_PAGEVIEWS
ANALYTICS_SCREENVIEWS
ANALYTICS_TIMED_EVENTS
BEAT_FEEDBACK
BEAT
BUDGETS
CATEGORIES
DEVICES
DISCOVERED_ACCOUNTS
DISCOVERED_TRANSACTIONS
GOALS
HOLDINGS
MEMBERS
NOTIFICATION_PROFILES
TAGGINGS
TAGS
TRANSACTIONS
USER_COMMUNICATION_PROFILES
USERS

Event types

Event type string
CREATED
DELETED
UPDATED

Example manifest file contents

1
2
3
4
ResourceType,EventType,RecordCount,EffectiveDate,FileSize,EncryptedFileSize,Checksum,FileName
USERS,DELETED,0,2020-06-14,1274,1198,8f3bd95d1c7dce50bee215dd8271bdc9b3409ef2cfb057cc7617f91686d28091,CLT-0858efd1-2d2e-6a5d-f2b5-c7dad42ef184.2020-06-14.users.deleted
USERS,UPDATED,0,2020-06-14,1274,1187,f3318a7071074bd0cb70bc4f0ce5d51cca0cc5bdfdc8d4b1054446f6fa6dbc98,CLT-0858efd1-2d2e-6a5d-f2b5-c7dad42ef184.2020-06-14.users.updated
TRANSACTIONS,DELETED,0,2020-06-14,3107,3057,5dc55906519b3936ab9dbc5857db8605cf71f875085d9b359e654d48042ce691,CLT-0858efd1-2d2e-6a5d-f2b5-c7dad42ef184.2020-06-14.transactions.deleted

Latest Changes

Date Documentation version Reference number Description of changes
2023.04.12 2023.001 P-718 Added:
  1. Added additional field is_mobile_webview to Analytics Events and Analytics Pageviews.
2022.08.30 2022.002 P-528 Added:
  1. Added a section to the introduction explaining the four resource groups, which ones are enabled by default, and which ones must be enabled separately.
  2. More information was documented about each of the resources in the analytics events group.
Updated:
  1. The data spec section was reorganized to reflect the resource groups.
2022.08.08 2022.001 P-504 Added:
  1. Undocumented fields were added to the specs for members, transactions, analytics events, analytics pageviews, and analytics screenviews.
Updated:
  1. A new changelog format was implemented to conform to the newest standards used in other areas of the docs. Previous entries in the old format are given below, unchanged.
Date Documentation version Description of changes
2021.11.29 2021.007 Endpoints

Added notification profiles to the list of resources available in a snapshot.

MX Reference Number: 475
2021.11.23 2021.006 Nexus v1

  • Several enumerated values were missing from the documentation for the notification_type and notification_type_name fields. These values are not new, but were incorrectly left out of the documentation.
MX Reference Number: G-465
2021.11.01 2021.005 Data Spec

  • Added documentation on the available_credit,cash_advance_apr,cash_surrender_value,death_benefit,has_monthly_transfer_limit,insured_name,is_personal,last_payment_on,loan_amount,monthly_transfer_count,pay_out_amount,pending_balance,premium_amount,statement_balance, and statement_on fields to the spec for accounts objects.
MX Reference Number: G-454
2021.10.04 2021.004 Guide

  • Added documentation on the FileName field for SFTP manifest files.
MX Reference Number: G-424
2021.08.30 2021.003 Data Spec

  • Added data specs for discovered accounts and discovered transactions.
MX Reference Number: G-470
2021.07.19 2021.002 Data Spec

  • Updated the definitions for the balance and available_balance fields to conform with those used across all MX documentation.
MX Reference Number: G-374
2021.03.19 2021.001 Data Spec

  • Added documentation on the displayed_at and has_been_displayed fields to the spec for beat objects.
MX Reference Number: G-304
2021.02.16 2021.002 Data Spec

  • Added documentation on the new user_communication_profile resource.
MX Reference Number: G-298
2021.01.19 2021.001 Data Spec

  • Added documentation on the EncryptedFileSize field for SFTP manifest files.
MX Reference Number: G-286
2021.01.08 2021.000 Data Spec

  • Added documentation for the is_relevant field in beats, and feed_localized_memo in transactions.
MX Reference Number: G-282
2020.11.11 2020.007 Data Spec

  • DISCOVERED_ACCOUNTS and DISCOVERED_TRANSACTIONS were removed from the list of the resource types that may be included in manifest files for SFTP delivery.
MX Reference Number: G-239
2020.10.27 2020.007 Data Spec

  • Added information explaining that resources with no data for a particualar day will still have an avro file with headers but no data generated which can be retrieved or delivered via SFTP.
MX Reference Number: G-246
2020.08.13 2020.006 Data Spec

  • Several date-related fields ending in _at were incorrectly documented as strings. They were corrected to integers.
MX Reference Number: G-210
2020.08.13 2020.005 Guide

  • In the “staging data” section, added the complete and correct order for consuming files.
MX Reference Number: G-209
2020.07.21 2020.004
  • Added information on manifest files for SFTP delivery.
MX Reference Number: G-197
2020.06.24 2020.003 Data Spec

  • Added information on beats
MX Reference Number: G-92
2020.04.27 2020.002 Data Spec

  • Added information analytics pageviews, analytics timed events, beat feedback, and notification profiles.
MX Reference Number: G-178
2020.04.14 2020.001 Data Spec

  • Added information on new account subtypes.
MX Reference Number: G-114
2020.04.02 2020.000 Data Spec

Added a new field to the user spec: created_at.MX Reference Number: G-102
2019.11.05 2019.007 Data Spec

Removed the examples column from data spec to avoid confusion. Fields that require examples are included in the definition.

MX Reference Number: 1310
2019.10.24 2019.006 Guide

  • Added an example on how to use byte serving for large avro files.
MX Reference Number: 1298
2019.08.09 2019.005 Data spec

  • Added two new fields to the data spec for users: email_is_verified and phone_is_verified.
MX Reference Number: 1255
2019.07.29 2019.004 Data spec

  • Added a new field to the transaction spec: feed_description.
MX Reference Number: 1249
2019.06.12 2019.003 Data spec

  • Added a new field to the account spec: is_internal.
MX Reference Number: 1224
2019.04.22 2019.002 Endpoints

  • Expanded the versioning section to include information on enhancements that can be expected within the current API version and enhancements that will require either a new API version or advanced notice to partners.
MX Reference Number: 1179
2019.01.28 2019.001 Data spec

  • Updated the definition of the total_account_value and feed_total_account_value fields on accounts. They now read:
    The sum of all the holdings associated with a particular account. This may sum to a negative value, and it does not represent an account balance. Max length is 14,2.
MX Reference Number: 1128
2018.10.22 2018.005 Data Spec

Documented the analytics event and analytics screenview objects and defined the associated fields.

MX Reference Number: 1060
2018.10.10 2018.004 Data Spec

Added new field “created_by” to Goals.

MX Reference Number: 1066
2018.07.18 2018.003 Data Spec

Added new fields:
  • Accounts:
  • “member_id”
  • Holdings:
  • “sector”
  • Transactions:
  • “is_international”
MX Reference Number: 1027
2018.06.05 2018.002 Data Spec

Added new fields to Members:
  • “connection_status”, “connection_status_id”, “connection_status_message”


MX Reference Number: 1014
2018.03.07 2018.001 Endpoints

Added goals to the list of resources available in a Snapshot.

MX Reference Number: 960
2017.11.08 2017.022 Endpoints

Added documentation on how to download data Snapshots.

MX Reference Number: 890
2017.11.07 2017.021 Data Spec

Moved the Resources section into a Data Spec page and added a submenu to separate Data Spec and Endpoints.

MX Reference Number: 888
2017.10.31 2017.020 Docs

Added information on the requirements for doing SFTP delivery of Reporting files.

MX Reference Number: 873
2017.10.19 2017.019 Docs

Added Account Type and Account Subtype lists for reference and changed enum lists to bullets instead of tables.

MX Reference Number: 864
2017.09.18 2017.018 Docs

Adding new fields to Holdings:
  • “bond_coupon_rate”, “bond_maturity_date”, “fixed_income_classification”, “isin”, “sedol”
MX Reference Number: 842
2017.09.06 2017.017 Docs

Adding Devices to Resources including the following fields:
  • “guid”, “make”, “model”, “os_name”, “os_version”, “updated_at”, “user_guid”, “user_id”
MX Reference Number: 832
2017.08.18 2017.016 Docs

Added “institution_guid” to Accounts Resource fields.

MX Reference Number: 817
2017.08.17 2017.015 Guide

Added new section “Schema Evolution” to explain avro schema evolution and MX addition of fields to Reporting in compliance with avro standards to support backwards compatibility.

MX Reference Number: 816
2017.08.08 2017.014 Docs

Added “top_level_category_guid” to Transactions resource schema.

*MX Reference Number: *
2017.07.31 2017.013 Docs

Added sample Java and Python code to the endpoint section.

Guide

Added suggested steps explaining how to generate sample test files by adding test users.

MX Reference Number: 804
2017.07.27 2017.012 Docs

Updated the endpoints section and curl example to add some more details and clarity.

Added sample Ruby code in addition to curl existing curl example.

MX Reference Number: 800, 802
2017.07.20 2017.011 Docs

Added the field “is_managed_by_user” to the Members resource fields. Added a note that “is_user_created” has been deprecated and replaced by “is_managed_by_user” but that both fields are present for backwards compatibility.

MX Reference Number: 793
2017.07.19 2017.010 Guide

Deprecated “check_number” in the transactions resource and added a note clarifying that “check_number_string” should be used instead.

MX Reference Number: 790
2017.06.26 2017.009 Guide

Added sample avro files.

MX Reference Number: 771
2017.06.20 2017.008 Docs

Added “tag_guid” to Taggings Resource fields.

MX Reference Number: 761
2017.06.19 2017.007 Docs

Added the following fields:
  • Accounts
  • “created_at”, “member_is_managed_by_user”
  • Holdings
  • “member_is_managed_by_user”
  • Taggings
  • “guid”, “member_is_managed_by_user”
  • Transactions
  • “account_id”, “created_at”, “is_personal”, “member_is_managed_by_user”
Added Tags to Resources.

MX Reference Number: 758
2017.04.12 2017.006 Docs

Added the following fields:
  • Holdings
  • “holding_type”, “revision”
  • Members
  • “successfully_aggregated_at”
  • Taggings
  • “revision”
  • Transactions
  • “category_guid”, “feed_transaction_type”, “is_overdraft_fee”, “is_payroll_advance”
MX Reference Number: 730
2017.04.04 2017.005 Docs

Added the following fields:
  • Holdings
  • “equity_classification”
  • Users
  • “birthday”, “postal_code”
MX Reference Number: 727
2017.03.31 2017.004 Guide

Added code example for parsing avro files to csv.

MX Reference Number: 723
2017.03.29 2017.003 Docs

Added “Available Resource Types” list to “API Endpoints” section. Clarified the descriptions of all “guid” and “id” fields. Added Taggings to Resources and documented the following fields:
  • Taggings
  • “transaction_id”, “transaction_guid”, “tag_name”, “updated_at”, “user_id”, “user_guid”
Guide

Added Taggings to the to the file consumption order.

MX Reference Number: 720
2017.03.21 2017.002 Docs

Reordered fields in Resources to match the order of the file headers.

Added Holdings and Categories to Resources and added the following fields to existing resources:
  • Accounts
  • “account_number”, “cash_balance”, “is_closed”, “is_hidden”, “last_payment”, “last_payment_at”, “nickname”, “payment_due_at”, “payment_due_on”, “property_type”
  • Categories
  • “guid”, “created_at”, “is_default”, “is_income”, “metadata”, “name”, “parent_guid”, “revision”, “updated_at”, “user_id”, user_guid”
  • Holdings
  • “guid”, “id”, “account_guid”, “classification”, “cost_basis”, “created_at”, “cusip”, “deleted_at”, “description”, “daily_change”, “is_deleted”, “market_value”, “metadata”, “purchase_price”, “shares”, “symbol”, “update”, “user_id”, user_guid”
  • Transactions
  • “date”, “description”, “has_been_viewed”, “is_bill_pay”, “is_direct_deposit”, “is_expense”, “is_fee”, “is_flagged”, “is_hidden”, “is_income”, “merchant_category_code”
  • Users
  • “is_disabled”, “logged_in_at”
Guide

Added Holdings and Categories to the file consumption order.

MX Reference Number: 713
2017.02.08 2017.001 Docs

Added Security section to overview about using TLS 1.2 or higher with known secure ciphers with requests.

MX Reference Number: 682
2017.01.25 2017.000 Docs

Fixed grammar mistakes in the response body format description. Added clarification to the availability of files, dealing with large files, and overview sections.

Guide

Added Reporting Guide to the API Guides.

MX Reference Number: 668
2016.11.15 2016.005 Docs

Fixed inconsistencies across Resources field documentation, added types to Accounts, Goals, Members, Transactions, Users.

Added Budgets to Resources including the following fields:
  • “guid”, “user_guid”, “user_id”, “parent_guid”, “category_guid”, “amount”, “created_at”, “is_exceeded”, “is_off_track”, “metadata”, “name”, “projected_spending”, “transaction_total”, “revision”, “updated_at”
MX Reference Number: 634
2016.09.27 2016.004 Docs

Added the following field to all Resources:
  • “metadata”
MX Reference Number: 604
2016.08.09 2016.003 Docs

Added clarity and fixed descriptions dealing with different date formats.

Added the following fields to all Resources:
  • “revision”, “updated_at”
MX Reference Number: 566
2016.04.04 2016.002 Docs

Added the following fields to Members:
  • “is_user_created”, “is_manual”
MX Reference Number: 444
2016.02.10 2016.001 Docs

Renamed field “institution_external_guid” to “institution_id” under Members in Resources.

Added the following fields to Transactions:
  • “has_been_split”, “parent_guid”
MX Reference Number: 391
2016.02.02 2016.000 Docs

Added section “Dealing With Large Files” explaining byte serving.

MX Reference Number: 385
2015.08.19 2015.007 Docs

Fixed some spelling errors.

MX Reference Number: 279
2015.08.17 2015.006 Docs

Fixed some formatting in Resources descriptions.

MX Reference Number: 272
2015.07.08 2015.005 Docs

Removed “member_guid” from Transactions in Resources.

Added the following fields to Resources:
  • Accounts
  • “id”, “user_id”
  • Members
  • “id”, “user_id”, “institution_external_guid”
  • Transactions
  • “id”, “user_id”
  • Users
  • “id”
MX Reference Number: 240
2015.06.16 2015.004 Docs

Reformatted curl example for readability.

MX Reference Number: 228
2015.06.05 2015.003 Docs

Added Goals to Resources including the following fields:
  • “account_guid”, “amount”, “completed_at”, “completed_on”, “created_at”, “created_on”, “current_amount”, “goal_type”, “guid”, “has_been_spent”, “is_complete”, “meta_type”, “name”, “position”, “projected_to_complete_at”, “user_guid”
Added “Goal Meta Type” section.

MX Reference Number: 223
2015.06.03 2015.002 Docs

Added sections for Versioning, IP Whitelist, and Accept header to bring these in line with the headers in our other docs.

MX Reference Number: 221
2015.04.22 2015.001 Docs

Changed Accept header to “application/vnd.mx.logs.v1+avro” in Overview section and curl example.

MX Reference Number: 195
2015.04.03 2015.000 Docs

Added Reporting API Documentation.

MX Reference Number: 165