Skip to main content

​
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.
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 use cases

You must work with MX to enable this feature.
Set the use_cases field so each member is associated with a use case, PFM or MONEY_MOVEMENT. This lets you:
  • Return only the data associated with a member’s use case.
  • Filter a user’s data by a single use case, even if MX has data for other use cases.
Members with the PFM use case aggregate data as usual. MX’s Personal Finance Management and Financial Insights products show data only for members with the PFM use case. Members with the MONEY_MOVEMENT use case don’t aggregate transaction data. For how use cases affect the Connect Widget, see Member use cases in the Connect Widget. In the Connections Widget, set connections_use_case_filter to true so the widget shows only members with the use cases you set in the same request. For examples, see Filter Connections.

​
Required actions

MX enables this feature for you. For existing integrations, MX also backfills the use_cases field on your existing members. Set use_cases to PFM, MONEY_MOVEMENT, or both on each of these requests:
  • Request Widget URL requests with a widget_type of connect_widget or connections_widget
  • All Create Member requests
  • All Update Member requests. Use Update Member to add, change, or remove a use case, but every member must keep at least one.
To aggregate a member’s transactions, the member must have the PFM use case. Otherwise, the request returns 403 Forbidden.

​
Filter by use case

The List Members, List Accounts, and List Transactions endpoints accept a use_case query parameter set to PFM or MONEY_MOVEMENT. For example:
See each endpoint’s page for details.

​
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 Fields

​
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.

​
Institution Blocking Errors

Blocked requests return the error object used for failed requests. Create Member, Update Member, and account verification requests can be rejected before they start because of the institution’s status or the institution’s status for your client. A blocked request returns 422 Unprocessable Entity with an error.type of unprocessable_entity_error, and the request isn’t processed. The error.message is written so you can display it to the end user. These checks use the institution’s status at the time of the request. If MX discovers that the institution is unavailable while aggregating the member, the request isn’t blocked. Instead, the member’s error field returns a code such as INSTITUTION_MAINTENANCE or INSTITUTION_UNAVAILABLE. See Member Connection Error Codes.

​
Member Connection Errors

When a member’s most recent aggregation fails, Read Member and Read Member Status include an error field on the member object. For the error object returned when a request fails, see Errors. The member’s error field is different from the error object returned when a request fails. A failed request returns a 4xx or 5xx HTTP status with a top-level error object that has message, status, and type fields. The member’s error field is returned in a successful response and explains why the member’s most recent aggregation didn’t succeed. The error field is null unless the most recent aggregation failed for one of the reasons in Member Connection Error Codes. Keep using the member’s connection status to decide what to do next, as described in Member Connection Statuses. When error is present, use it for the specific reason and a message you can show the end user.

​
Member Error Fields

​
Member Connection Error Codes

The following error codes can be returned when aggregating a member.

​
Localize Member Error Messages

Read Member and Read Member Status return error_message and user_message in the language set by the Accept-Language request header. Supported languages are English (en), Spanish (es), and French (fr). A regional variant uses its base language, so fr-CA returns French.
  • If you send an unsupported language, messages are returned in English.
  • If you don’t send the header, messages are returned in the default locale configured for your client, or in English if no default is configured.
The locale field shows which language was returned.

​
Handle Member Connection Errors

  1. Check the member’s connection status and follow the next steps in Member Connection Statuses.
  2. If error is present, display user_message to the end user.
  3. Use error_code for application logic, such as starting OAuth reauthorization for REAUTHORIZATION_REQUIRED or prompting for new credentials for INVALID_CREDENTIALS.
  4. Log error_message for troubleshooting.