Accounts overview - MX Documentation

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.

ANY

Not provided by data partner or invalid number provided.

NONE — Represents a null or unspecified account subtype

CHECKING

SAVINGS

MONEY_MARKET
CERTIFICATE_OF_DEPOSIT

LOAN

AUTO
STUDENT
SMALL_BUSINESS
PERSONAL
PERSONAL_WITH_COLLATERAL
HOME_EQUITY
BOAT
POWERSPORTS
RV
HELOC

CREDIT_CARD

INVESTMENT

PLAN_401_K, PLAN_403_B, PLAN_529, IRA, ROLLOVER_IRA, ROTH_IRA
TAXABLE, NON_TAXABLE, BROKERAGE, TRUST
UNIFORM_GIFTS_TO_MINORS_ACT, UNIFORM_TRANSFER_TO_MINORS_ACT
PLAN_457, PENSION, EMPLOYEE_STOCK_OWNERSHIP_PLAN
SIMPLIFIED_EMPLOYEE_PENSION, SIMPLE_IRA, PLAN_ROTH_401_K
FIXED_ANNUITY, VARIABLE_ANNUITY, HSA, TAX_FREE_SAVINGS_ACCOUNT
INDIVIDUAL, REGISTERED_RETIREMENT_INCOME_FUND
CASH_MANAGEMENT_ACCOUNT, EMPLOYEE_STOCK_PURCHASE_PLAN
REGISTERED_EDUCATION_SAVINGS_PLAN, PROFIT_SHARING_PLAN
PLAN_401_A, SARSEP_IRA
FIXED_ANNUITY_TRADITIONAL_IRA, VARIABLE_ANNUITY_TRADITIONAL_IRA
SEPP_IRA, INHERITED_TRADITIONAL_IRA
FIXED_ANNUITY_ROTH_IRA, VARIABLE_ANNUITY_ROTH_IRA, INHERITED_ROTH_IRA
COVERDELL, ADVISORY_ACCOUNT, BROKERAGE_MARGIN
CHARITABLE_GIFT_ACCOUNT, CHURCH_ACCOUNT, CONSERVATORSHIP
CUSTODIAL, DEFINED_BENEFIT_PLAN, DEFINED_CONTRIBUTION_PLAN
EDUCATIONAL, ESTATE, EXECUTOR
GROUP_RETIREMENT_SAVINGS_PLAN, GUARANTEED_INVESTMENT_CERTIFICATE
HRA, INDEXED_ANNUITY, INVESTMENT_CLUB
IRREVOCABLE_TRUST, JOINT_TENANTS_BY_ENTIRITY
JOINT_TENANTS_COMMUNITY_PROPERTY, JOINT_TENANTS_IN_COMMON
JOINT_TENANTS_WITH_RIGHTS_OF_SURVIVORSHIP, KEOUGH_PLAN
LIFE_INCOME_FUND, LIVING_TRUST, LOCKED_IN_RETIREMENT_ACCOUNT
LOCKED_IN_RETIREMENT_INVESTMENT_FUND, LOCKED_IN_RETIREMENT_SAVINGS_ACCOUNT
MONEY_PURCHASE_PLAN, PARTNERSHIP, PLAN_409_A, PLAN_ROTH_403_B
REGISTERED_DISABILITY_SAVINGS_PLAN, REGISTERED_LOCKED_IN_SAVINGS_PLAN
REGISTERED_PENSION_PLAN, REGISTERED_RETIREMENT_SAVINGS_PLAN
REVOCABLE_TRUST, ROTH_CONVERSION, SOLE_PROPRIETORSHIP
SPOUSAL_IRA, SPOUSAL_ROTH_IRA, TESTAMENTARY_TRUST
THRIFT_SAVINGS_PLAN, INHERITED_ANNUITY, CORPORATE_ACCOUNT
LIMITED_LIABILITY_ACCOUNT

LINE_OF_CREDIT

MORTGAGE

PROPERTY

APPLIANCES, ART, COMPUTER, ELECTRONICS, FURNITURE
JEWELRY, MISCELLANEOUS, REAL_ESTATE, SPORTS_EQUIPMENT, VEHICLE

CASH

INSURANCE

VEHICLE_INSURANCE, DISABILITY, HEALTH, LONG_TERM_CARE
PROPERTY_AND_CASUALTY, UNIVERSAL_LIFE, TERM_LIFE, WHOLE_LIFE
ACCIDENTAL_DEATH_AND_DISMEMBERMENT, VARIABLE_UNIVERSAL_LIFE

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 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. 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.
`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 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 users connect accounts via OAuth with supported institutions, the institution provides a TAN instead of the actual account number. This allows third-party applications to interact with an account, such as facilitating ACH money movement, without accessing the user’s actual account number. 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. Understanding account objects: MX uses two objects that display account numbers differently:

Feature	`accounts` object	`account_numbers` object
Available through	List Accounts, List Accounts by Member, Read Account, and Read Account by Member	List Account Numbers by Member and Read Account Numbers by Account
Set by	Create Member or through the Connect Widget when the user connects to an institution	Verify Member or Create Member
Account number format	`feed_account_number` field contains a masked account number (usually last 4 digits) from the institution	Contains either the full account number or a TAN (for supported institutions)
Last 4 digits	Included in masked format	Does not include a field with the last 4 digits
Data source	The `*_set_by` field shows the data source (typically `FEED` unless you send a user-specified value)	N/A
Can be null	Yes, if the institution doesn’t provide it	No
TAN matching	N/A	When a TAN is returned, it won’t match the masked digits from the `accounts` object

Key properties:

The TAN and routing number are valid for ACH transfers only when used together. They won’t work for wire transfers, and third-party verification services may not recognize them.
Using a TAN with a different routing number—even from the same institution—will cause the transfer to fail.
You cannot reliably match TANs to your existing account records using the last 4 digits. The masked account number from the accounts object won’t necessarily match the corresponding TAN.
OAuth connections: Call /users/{user_guid}/members/{member_guid}/account_numbers to retrieve the TAN in the account_number field.
Non-OAuth connections: Return traditional (non-tokenized) account and routing numbers.
The standard accounts object endpoints always return masked account numbers, regardless of connection type.

Do not display the TAN in your UI; users won’t recognize it. Show the masked account number from the /users/{user_identifier}/accounts endpoint instead.

Institution-specific behavior:

Institution	TAN Behavior
Chase	TAN becomes invalid if MX revokes consent, the user revokes consent directly, or Chase flags the account for fraud.
U.S. Bank	TAN remains active for money movement even after the MX connection is deleted. See the U.S. Bank Developer Portal for details.

​Account Types

​Account Fields

​Account Number Fields

​Account Owner Fields

​Tokenized Account Numbers

Account Types

Account Fields

Account Number Fields

Account Owner Fields

Tokenized Account Numbers