> ## 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`, `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`
* `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_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](https://developer.usbank.com/) for details. |