Accounts Overview

The Accounts endpoints represent a user's checking, savings, mortgage, 401(k), or other types of accounts held by a financial institution.

An account belongs to a member, which represents the user's overall relationship with a particular financial institution. A checking account may be just one part of a larger relationship that could also include a car loan and a savings account.

Accounts—and the transactions associated with them—are updated every 24 hours, unless the associated user is disabled.

You can also create manual accounts. Since a manual account has no credentials tied to the member, the account will never aggregate or include data from a data feed. All manual accounts are automatically created under the Manual Institution member.

Account Types

Each item at the top level of this list represents an account_type.

The items in each dropdown represent an account_subtype. When setting or retrieving an account_subtype, if the account_subtype is null, it will be treated as NONE.

Items under Property represent a property_type.

Account 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

Account Fields

Field	Data Type	Description
account_number	String	The account number associated with the account. This will typically be a masked or partial account number.
account_number_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
account_ownership	String	The type of ownership associated with the account such as UNKNOWN, INDIVIDUAL, JOINT, MULTIPLE, NULL. NULL is returned if not received in the data feed.
annuity_ policy_to_date	DateTime	The date until which the policy is in effect.
annuity_provider	String	The provider of the insurance policy.
annuity_term_year	Integer	The effective duration of an insurance policy (one year, five years, etc.).
apr	Decimal	The annual percentage rate associated with the account.
apr_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
apy	Decimal	The annual percentage yield associated with the account.
apy_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
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_balance_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
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.
available_credit_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
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.
balance_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
calculated_apr	Decimal	An APR for the account, calculated using transaction data. This is currently calculated only for accounts with type = CREDIT_CARD, but more account types may be added.
cash_balance	Decimal	The cash balance of the account.
cash_balance_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
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.
cash_surrender_value_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
created_at	String	The date and time at which the account was created on the MX Platform.
credit_limit	Decimal	The credit limit associated with the account.
credit_limit_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
currency_code	String	The three-character ISO 4217 currency code.
currency_code_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
day_payment_is_due	Integer	The day of the month the payment is due. For example, the 14th is passed as 14.
day_payment_is_due_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
death_benefit	Integer	The amount paid to the beneficiary of the account upon death of the account owner.
death_benefit_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
federal_insurance_status	String	The federal insurance status of the account. Indicates whether the account is insured by the FDIC or NCUA (FDIC for banks, NCUA for credit unions). The possible values are INSURED and NOT_INSURED.
feed_account_number	String	The account number, as provided by our data feed. See account_number for more information.
feed_account_subtype	Integer	The account subtype, as provided by our data feed. See subtype for more information.
feed_account_type	Integer	The account type, as provided by our data feed. See type for more information.
feed_apr	Decimal	The apr, as provided by our data feed. Max length is 10,6.
feed_apy	Decimal	The apy, as provided by our data feed. Max length is 10,6.
feed_available_balance	Decimal	The available balance, as provided by our data feed. Max length is 14,2.
feed_balance	Decimal	The balance, as provided by our data feed. Max length is 14,2.
feed_cash_balance	Decimal	The cash balance, as provided by our data feed. Max length is 14,2.
feed_cash_surrender_value	Decimal	The cash surrender value, as provided by our data feed. Max length is 14,2.
feed_credit_limit	Decimal	The credit limit, as provided by our data feed. Max length is 10,2.
feed_currency_code	String	The ISO 4217 three-character currency code, as provided by our data feed (e.g. USD).
feed_day_payment_is_due	Integer	The day of the month the payment is due, as provided by our data feed (e.g. Mar 14th is passed as 14).
feed_death_benefit	Integer	The death benefit, as provided by our data feed.
feed_holdings_value	Decimal	The holdings value, as as provided by our data feed. Max length is 14,2.
feed_interest_rate	Decimal	The interest rate, as provided by our data feed. Max length is 10,6.
feed_is_closed	Boolean	Whether or not the account has been closed, as provided by our data feed.
feed_last_payment	Decimal	The last payment, as provided by our data feed. Max length is 10,2.
feed_last_payment_at	string	Date and time the last payment was at, as provided by our data feed. Represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00).
feed_loan_amount	Decimal	Amount of the loan, as provided by our data feed. Max length is 14,2.
feed_matures_on	String	Maturity date, as provided by our data feed. Represented in ISO 8601 format (e.g. 2011-03-28).
feed_minimum_balance	Decimal	The minimum balance, as provided by our data feed. Max length is 14,2.
feed_minimum_payment	Decimal	The minimum payment, as provided by our data feed. Max length is 10,2.
feed_name	String	The name of the account, as provided by our data feed.
feed_payment_due_at	String	Date and time the payment is due at, as provided by our data feed. Represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00).
feed_payoff_balance	Decimal	The payoff balance, as provided by our data feed. Max length is 14,2.
feed_routing_number	String	The routing number, as provided by our data feed. See routing_number for more information.
feed_started_on	String	The started on date, as provided by our data feed. Represented in ISO 8601 format (e.g. 2011-03-28).
feed_statement_balance	Decimal	The account statement balance, as provided by our data feed. Max length is 14,2.
feed_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. Max length is 14,2.
guid	String	The unique identifier for the account. Defined by MX.
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
imported_at	String	The date and time at which the account was last successfully aggregated and received data.
institution_code	String	A unique identifier for the institution associated with this account. Defined by MX.
institution_guid	String	A unique identifier for the institution associated with this account. Defined by MX.
insured_name	String	The name of the insured individual.
interest_rate	Decimal	The interest rate associated with the account.
interest_rate_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
is_closed	Boolean	This indicates whether an account has been closed. Closed accounts will no longer update balance or transaction information.
is_closed_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
is_hidden	Boolean	This indicates whether the account is hidden. Hidden accounts can still have an active balance and receive transactions. Defaults to false.
is_manual	Boolean	This indicates whether the account is manually created.
last_payment	Decimal	The amount of the most recent payment on the account.
last_payment_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
last_payment_at	String	The date and time of the most recent payment on the account.
last_payment_at_set_by	String	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
loan_amount	Decimal	The amount of the loan associated with the account.
loan_amount_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
margin_balance	Decimal	Represents the amount of debt the investor owes to the broker for the use of margin. It can be positive or negative, depending on the performance of the investments made with the borrowed funds. A positive margin balance indicates that the securities purchased on margin have increased in value, whereas a negative margin balance signifies that the securities have decreased in value.
matures_on	String	The date on which the account matures.
matures_on_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
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. Members created with the managed member feature will have this field set to false.
metadata	String	Additional information a partner can store on the account. NOTE: this may potentially be overwritten by the data provider when data is refreshed through aggregation.
minimum_balance	Decimal	The minimum balance associated with the account.
minimum_balance_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
minimum_payment	Decimal	The minimum payment required for an account. This can apply to any debt account.
minimum_payment_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
name	String	The human-readable name for the account.
name_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
nickname	String	An alternate name for the account.
nickname_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
original_balance	Decimal	The original balance associated with the account. This will always be positive.
original_balance_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
pay_out_amount	Decimal	The amount paid out to the insured individual or beneficiary under the conditions of the insurance policy.
payment_due_at	String	The date and time at which the next payment is due on the account.
payment_due_at_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
payoff_balance	Decimal	The payoff balance for a debt account. This will normally be a positive number.
payoff_balance_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
premium_amount	Decimal	The insurance policy's premium amount.
property_type	String	Subtype if the account type is PROPERTY. This field should be ignored unless the type is set to PROPERTY.
routing_number	String	The routing number for the account.
started_on	String	The date on which the loan from a debt account started.
started_on_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
statement_balance	Decimal	The balance at the end of the account's last statement period.
statement_balance_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
subtype	String	The account's subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY.
subtype_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
today_ugl_amount	Decimal	The unrealized gain/loss amount for the day for the account.
today_ugl_percentage	Decimal	The unrealized gain/loss percentage for the date for the account.
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.
total_account_value_set_by	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
total_account_value_ugl	Decimal	The unrealized gains and losses represent the amount the account has gained or lost based on the purchase price. This is calculated by subtracting the purchase price from the current market value. It does not affect the account until the positions are sold and "realized". 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.
type_set_by.	Integer	The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ).
updated_at	String	The date and time at which the account was most recently updated.
user_guid	String	The unique identifier for the user associated with the account. Defined by MX.
user_id	String	The unique, partner-defined, identifier for the user associated with this account.

Account Number Fields

Field	Data Type	Description
account_guid	String	The unique identifier for the account associated with a particular set of account and routing numbers. Defined by MX.
account_number	String	The banking account number associated with a particular account.
guid	String	The unique identifier for the account number. Defined by MX.
institution_number	String	The three-digit number identifying a Canadian banking institution.
loan_reference_number	String	The reference number of the student loan.
loan_guarantor	String	The guarantor of the student loan.
member_guid	String	The unique identifier for the member associated with a particular set of account and routing numbers. Defined by MX.
passed_validation	Boolean	This indicates whether the account and routing numbers passed MX's internal validity checks. If true, the account and routing/transit numbers are likely (but not guaranteed) to be valid. If false, either the account number, routing/transit number, or both are likely invalid.
routing_number	String	The routing number for the financial institution associated with the account.
sequence_number	String	The sequence number of the student loan.
transit_number	String	The five-digit number identifying the branch of a Canadian financial institution.
user_guid	String	The unique identifier for the user associated with a particular set of account and routing numbers. Defined by MX.

Account Owner Fields

Field	Data Type	Description
account_guid	String	The unique identifier for the account associated with the account owner. Defined by MX.
address	String	The account owner's street address.
city	String	The account owner's city.
country	String	The account owner's country.
email	String	The account owner's email address.
first_name	String	The account owner's first name. This may also include a middle name. This field will be null unless name splitting has been enabled. Contact MX to have this feature enabled.
guid	String	The unique identifier for the account owner. Defined by MX.
last_name	String	The account owner's last name. This field will be null unless name splitting has been enabled. Contact MX to have this feature enabled.
member_guid	String	The unique identifier for the member associated with the account owner. Defined by MX.
owner_name	String	The account owner's name.
phone	String	The account owner's phone number.
postal_code	String	The the account owner's postal code.
state	String	The account owner's state.
user_guid	String	The unique identifier for the user associated with the account owner. Defined by MX.

Tokenized Account Numbers

Tokenized Account Numbers (TANs) are substitute account numbers used for secure ACH money movement. When an end user connects an account via an OAuth connection, certain financial institutions provide a TAN instead of the user's actual account number.

This practice enhances security and provides users with greater control. Because each application receives a unique TAN for the same bank account, users or their financial institutions can manage access on a per-application basis without exposing the underlying account details.

The MX platform currently supports TANs from Chase and U.S. Bank.

Using TANs for ACH Payments

The TAN and associated routing number are valid for money movement on the ACH network but only when used together. This combination won't work for other purposes, such as wire transfers, and third-party verification services may not recognize them. Using the TAN with a different routing number—even one from the same institution—will cause the transfer to fail.

Best Practice

To avoid confusing the end user, don't display the TAN in your application's UI. The user won't recognize this number. Instead, display the masked account number provided in the account_number field from the /users/{user_guid}/accounts endpoint.

Connection Types

• OAuth: For supported institutions like Chase and U.S. Bank, a call to /users/{user_guid}/members/{member_guid}/account_numbers will return a TAN in the account_number field.
• Non-OAuth Connections: These connections return traditional (non-tokenized) account and routing numbers.

Institution-Specific Behavior

The lifecycle and behavior of a TAN can vary by financial institution.

Chase

TANs issued by Chase will become invalid and ACH transfers will fail under the following conditions:

• MX revokes consent.
• The end user revokes consent directly with Chase.
• Chase flags the account for fraudulent activity.

U.S. Bank

TANs issued by U.S. Bank won't become invalid if the end user revokes consent or deletes the connection. They remain active for money movement even after the associated MX connection is no longer active.

For more information, reference the U.S. Bank Developer Portal.