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, 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
UNIFORM_TRANSFER_TO_MINORS_ACT, 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_ownership`	String	The type of ownership associated with the `account` such as `UNKNOWN`, `INDIVIDUAL`, `JOINT`, `MULTIPLE`, `NULL`.
`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`.
`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.
`available_credit`	Decimal	The amount of credit available for use in liability accounts like credit cards and lines of credit.
`balance`	Decimal	The current balance of the account. `PENDING` transactions are typically not taken into account with the current balance.
`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.
`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`.
`currency_code`	String	The three-character ISO 4217 currency code.
`day_payment_is_due`	Integer	The day of the month the payment is due. For example, the 14th is passed as `14`.
`death_benefit`	Integer	The amount paid to the beneficiary of the account upon death of the account owner.
`federal_insurance_status`	String	The federal insurance status of the account. Indicates whether the account is insured by the FDIC or NCUA.
`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.
`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_manual`	Boolean	This indicates whether the account is manually created.
`last_payment_at`	String	The date and time of the most recent payment on the `account`.
`last_payment`	Decimal	The amount of the most recent payment on the `account`.
`loan_amount`	Decimal	The amount of the loan associated with the `account`.
`margin_balance`	Decimal	Represents the amount of debt the investor owes to the broker for the use of margin.
`matures_on`	String	The date on which the `account` matures.
`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`. NOTE: this may potentially be overwritten by the data provider.
`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.
`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`	String	The date and time at 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.
`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 `account_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.
`statement_balance`	Decimal	The balance at the end of the account’s last statement period.
`subtype`	String	The account’s subtype, e.g., `PLAN_401_K`, `MONEY_MARKET`, or `HOME_EQUITY`.
`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.
`total_account_value_ugl`	Decimal	The unrealized gains and losses represent the amount the account has gained or lost based on the purchase price.
`type`	String	The general or parent type of the `account`.
`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.
`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.
`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.
`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