Members Overview

Members represent the connection between an end user and a financial institution. This institution may represent your institution or another one from which MX is aggregating data.

Member Accounts

A member can have multiple accounts. For instance, an end user might have both a savings account and a checking account at Wells Fargo. In this case, two separate account objects will exist on the MX platform, both associated with a single member representing the Wells Fargo connection.

Every account belongs to exactly one member.

Member Creation

Members can be created by you when using our API or by end users when using the Connect Widget.

note

Duplicate members aren’t allowed on the MX platform. A duplicate member is when a user attempts to connect to an institution they’re already connected to using the same credentials.

Member Aggregation

Aggregation is the process of gathering data for a member from its associated institution. To gather data from an institution, the user must authenticate with the institution using one of the following authentication methods:

• OAuth: The end user connects to an institution using OAuth. They must be present until the OAuth connection completes.
• Credentials: The end user connects to an institution using their credentials for that institution.

Some institutions exclusively support OAuth, while others may not support it at all. Each institution has a supports_oauth field.

The connection_status of a member reflects the state of aggregation with a specific institution.

For a detailed explanation of possible statuses, their meanings, and recommended actions, see Member Connection Statuses.

Member Connection Statuses

The connection_status indicates the state of a member's aggregation, meaning the state of a user connecting to a particular institution.

The connection_status field indicates the current state of an aggregation, meaning the state of a user connecting to a particular institution. For instance:

• CREATED means the member has just been created.
• CHALLENGED means the process has run into multifactor authentication.
• FAILED means the process was unsuccessful.

The connection statuses CREATED, UPDATED, DELAYED, and RESUMED represent transient states for different points in the process and don't require a specific action or end-user input. They may, however, require you to keep making read requests on the member until an actionable status or an end state appears.

The connection statuses PREVENTED, DENIED, IMPEDED, IMPAIRED, REJECTED, EXPIRED, LOCKED, IMPORTED, DISABLED, DISCONTINUED, and CLOSED represent end states that require you to start a new connection, and possibly end-user input, for future success.

Here are all the member statuses you might encounter, what they mean, and what to do about them.

Integer Value	Status	Definition	Next Steps	End-User Message
null	null	The member exists but does not have credentials. A member that does not aggregate (e.g., a manual member) will always have this status.	None.	None.
0	CREATED	The member is new and has not yet been aggregated.	Aggregate the member once the end user logs in; poll for a status update.	Connecting to [...] ...
1	PREVENTED	The end user's entered credentials have failed to connect three times in a row. MX has locked the account to avoid locking the end user out of their account on the financial institution's website. The end user must reenter their username and password to continue updating their data.	Display end-user message; after end user has updated their credentials, aggregate again.	The last 3 attempts to connect have failed. Please re-enter your credentials to continue importing data.
2	DENIED	The credentials provided for the member were invalid.	Display end-user message; after end user has updated their credentials, aggregate again.	The credentials entered do not match your credentials at this institution. Please re-enter your credentials to continue importing data.
3	CHALLENGED	The connection is waiting for the end user to complete a multifactor authentication (MFA) challenge. This is not an error and will change to an EXPIRED status if the end user fails to complete MFA.	Display end-user message; follow MFA pathway; after the user answers MFA, poll for a status update.	To authenticate your connection to [...], please answer the following challenge(s).
4	REJECTED	An MFA challenge was answered incorrectly.	Display end-user message; another challenge may follow or aggregation may need to be restarted.	The answer or answers provided were incorrect. Please try again.
5	LOCKED	The financial institution is preventing authentication. The end user must go to the FI's website or contact the financial institution.	Display end-user message.	Your account is locked. Please log in to the appropriate website for [...] and follow the steps to resolve the issue.
6	CONNECTED	The member was successfully authenticated and data is now aggregating.	Display the account as having been connected.	Connected to [...] ...
7	IMPEDED	The end user’s attention is required at their online banking institution, e.g., there is a marketing message that must be viewed, terms and conditions that must be accepted, etc.	Display end-user message.	Your attention is needed at this institution's website. Please log in to the appropriate website for [...] and follow the steps to resolve the issue.
8	RECONNECTED	The member has been migrated to a new data source and aggregation is likely to trigger one-time password MFA. MX will not perform background aggregation in order to avoid unnecessarily disruptive texts, emails, etc. The member must be re-aggregated in the foreground with the end user present.	Aggregate the member once the end user logs in; poll for a status update.	Reconnecting to [...] ...
9	DEGRADED	Aggregation has failed at least three times within a short period of time. This could be due to website maintenance or other factors that are preventing account aggregation.	Display end-user message.	We are upgrading this connection. Please try again later.
10	DISCONNECTED	Aggregation has failed at least three times and has not succeeded for at least two weeks.	Display end-user message.	It looks like your data from [...] cannot be imported. We are working to resolve the issue.
11	DISCONTINUED	The connection to this financial institution is no longer available.	Display end-user message.	Connections to this institution are no longer supported. You may create a manual account and use manual transactions to track data for this account.
12	CLOSED	The end user, MX, the client, or a partner has marked the member as closed.	Display end-user message.	This connection has been closed. You may track this account manually. If reopened, you may connect the institution again.
13	DELAYED	Aggregating the member has taken longer than expected and it has not yet been connected. This can be due to reasons outside of MX's control, such as internet bandwidth, problems at the financial institution's website, and other factors.	Display end-user message; poll for a status update.	Importing your data from [...] may take a while. Please check back later.
14	FAILED	Aggregation failed without being connected. Most aggregation issues are temporary and self-resolve after 24 hours.	Display end-user message; try aggregating again later.	There was a problem validating your credentials with [...]. Please try again later.
15	UPDATED	The member has been updated — i.e., credentials have been updated — but it has not yet been connected.	Aggregate the member once the end user logs in; poll for a status update.	Connecting to [...] ...
16	DISABLED	Aggregation has been momentarily paused, but the member is still connected.	Display end-user message.	Importing data from this institution has been disabled. Please contact us if you believe it has been disabled in error.
17	IMPORTED	MX does not have credentials and will not try to aggregate the member until the end user provides credentials.	Display end-user message; re-aggregate after the end user updates credentials.	You must re-authenticate before your data can be imported. Please enter your credentials for [...].
18	RESUMED	The answer to an MFA challenge was received, but it is not yet clear whether it was correct.	Poll for a status update.	Connecting to [...] ...
19	EXPIRED	The MFA answer was not provided within the time allotted by the financial institution.	Display end-user message; re-aggregate the member if the end user initiates it.	The answer or answers were not provided in time. Please try again.
20	IMPAIRED	The member is missing some or all credentials needed in order to connect.	Display end-user message; re-aggregate after the end user updates credentials.	You must re-authenticate before your data can be imported. Please enter your credentials for [...].
21	PENDING	The member is using OAuth to authenticate credentials and still needs to go through the financial institution's OAuth process. A PENDING status will appear only on members less than one hour old with is_oauth: true. Members that stay PENDING longer than one hour will be deleted by MX.	Redirect the end user to the oauth_window_uri provided in the create member response, or request one through the generate OAuth window URI endpoint.	None.

Member Fields

Field	Data Type	Definition
aggregated_at	String	The date and time the most recent aggregation-type job was started, given in ISO 8601 format with a time component. A job will automatically be started when a member is created or its credentials are updated, unless the skip_aggregation parameter is used. Jobs can also be started via manual aggregations, background aggregations, API endpoints, or when opening an MX widget. A job can be a normal aggregation, or a premium job such as identification, verification, fetching statements, or fetching an extended transaction history. If a member is deleted and then re-created with the skip_aggregation parameter set to true or if it is re-created within the throttle window (typically three hours), the previous value will be returned.
background_aggregation_is_disabled	Boolean	This indicates whether background aggregation is disabled for the member.
connection_status	String	This indicates the state of a member's aggregation.
connection_status_message	String	A message that can be displayed to the user to help them navigate the connection and aggregation process.
challenges	Array	An array of challenge objects that may be required during the aggregation process. Only present when checking member status.
guid	String	The unique identifier for the member. Defined by MX.
has_processed_account_numbers (Deprecated)	Boolean	This indicates whether account numbers have been processed for the member. Only present when checking member status.
has_processed_accounts (Deprecated)	Boolean	This indicates whether accounts have been processed for the member. Only present when checking member status.
has_processed_transactions (Deprecated)	Boolean	This indicates whether transactions have been processed for the member. Only present when checking member status.
id	String	The partner-defined unique identifier for the member. It must be unique for all members belonging to all users within the client.
institution_code	String	The unique code for the institution associated with the member. Defined by MX.
institution_guid	String	The unique identifier for the institution associated with the member. Defined by MX.
is_authenticated	Boolean	This indicates whether the member has been successfully authenticated with the institution. Only present when checking member status.
is_being_aggregated	Boolean	This indicates whether the member was being aggregated at the time of the request.
is_managed_by_user	String	This indicates whether the member is managed by the user or the MX partner. Members created with the managed member feature will have this field set to false.
is_manual	Boolean	This indicates whether the member is for manually created accounts.
is_oauth	Boolean	This indicates whether the member uses OAuth to authenticate. Defaults to false.
metadata	String	Additional information you can store on this member.
most_recent_job_detail_code	String	(Deprecated) This field is no longer used and will be removed at a future date.
most_recent_job_detail_text	String	(Deprecated) This field is no longer used and will be removed at a future date.
most_recent_job_guid	String	The unique identifier for the most recent job. Defined by MX.
name	String	The name of the member.
needs_updated_credentials	String	Internal field used by MX in some circumstances. When set to true, MX will not attempt to aggregate the member. It will be set to false automatically when the member's credentials are updated.
oauth_window_uri	String	When connecting a member using OAuth, this field will contain the URL to send the user to in order to authenticate, otherwise it will be blank.
successfully_aggregated_at	String	The date and time the member was last successfully aggregated.
use_cases	Array	The use case associated with the member. Valid values are PFM and MONEY_MOVEMENT. Only set this if you've met with MX and have opted in to using this field.
user_guid	String	The unique identifier for the user associated with the member. Defined by MX.
user_id	String	The unique partner-defined identifier for the user associated with the member.