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:

Users
Members
Accounts
Transactions
Holdings
Categories
Tags
Taggings
Goals
Budgets
Notification Profiles
Beat
Beat Feedback
Devices
Analytics Events
Analytics Page Views
Analytics Screen Views
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:

Helios Mobile App
MoneyMap
Nexus API

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.

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):

Atrium API
Batch API
Helios Mobile App
MDX Real Time
MoneyMap, including the Connect and Connections widgets
Nexus API
Platform API
SSO API

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.

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):

Atrium API
Batch API
Helios Mobile App
MDX Real Time
MoneyMap, including the Connect and Connections widgets
Nexus API
Platform API
SSO API

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

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

Date	Documentation version	Reference number	Description of changes
2023.04.12	2023.001	P-718	Added: Added additional field `is_mobile_webview` to Analytics Events and Analytics Pageviews.
2022.08.30	2022.002	P-528	Added: Added a section to the introduction explaining the four resource groups, which ones are enabled by default, and which ones must be enabled separately. More information was documented about each of the resources in the analytics events group. Updated: The data spec section was reorganized to reflect the resource groups.
2022.08.08	2022.001	P-504	Added: Undocumented fields were added to the specs for members, transactions, analytics events, analytics pageviews, and analytics screenviews. Updated: 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.

Added:

Added additional field is_mobile_webview to Analytics Events and Analytics Pageviews.

2022.08.30

2022.002

P-528

Added:

Added a section to the introduction explaining the four resource groups, which ones are enabled by default, and which ones must be enabled separately.
More information was documented about each of the resources in the analytics events group.

Updated:

The data spec section was reorganized to reflect the resource groups.

2022.08.08

2022.001

P-504

Added:

Undocumented fields were added to the specs for members, transactions, analytics events, analytics pageviews, and analytics screenviews.

Updated:

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