> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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`.
Not provided by data partner or invalid number provided.
* `NONE` — Represents a null or unspecified account subtype
* `MONEY_MARKET`
* `CERTIFICATE_OF_DEPOSIT`
* `AUTO`
* `STUDENT`
* `SMALL_BUSINESS`
* `PERSONAL`
* `PERSONAL_WITH_COLLATERAL`
* `HOME_EQUITY`
* `BOAT`
* `POWERSPORTS`
* `RV`
* `HELOC`
* `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`
* `APPLIANCES`, `ART`, `COMPUTER`, `ELECTRONICS`, `FURNITURE`
* `JEWELRY`, `MISCELLANEOUS`, `REAL_ESTATE`, `SPORTS_EQUIPMENT`, `VEHICLE`
* `VEHICLE_INSURANCE`, `DISABILITY`, `HEALTH`, `LONG_TERM_CARE`
* `PROPERTY_AND_CASUALTY`, `UNIVERSAL_LIFE`, `TERM_LIFE`, `WHOLE_LIFE`
* `ACCIDENTAL_DEATH_AND_DISMEMBERMENT`, `VARIABLE_UNIVERSAL_LIFE`
## 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 (Chase and U.S. Bank), the institution provides a TAN instead of the actual account number. This enhances security and gives users greater control—each application receives a unique TAN for the same bank account, allowing per-application access management without exposing underlying account details.
**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.
* 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.
Do not display the TAN in your UI—users won't recognize it. Show the masked account number from the `/users/{user_guid}/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](https://developer.usbank.com/) for details. |