Account Owner Identification Guide
MX's identification/account ownership data is offered in the context of the Nexus API and relies on the resources of that RESTful API to function properly. Specifically, this means following the general workflow below. Keep in mind that depending on your specific situation, it may be possible to skip several of these steps. For instance, if you already have a user with member, you may start by immediately calling the identify endpoint.
- Creating a
user(this is technically done using the MDX Real Time API). - Getting an API token for that
user(this is technically done using the MX SSO API). - Getting a session token for that
user. - Creating a
memberwith the correct institution code and credentials required by that institution. - Calling the identify endpoint if needed.
- Polling the member's
connection_statusand answering MFA if necessary. - Reading the collected data with the list account owners endpoint.
Create a User
Get an API Token
Next, you'll use the SSO API to the an api_token. This token will be used to open a Nexus session in step 3.
Remember that the user_id passed in this request must match the id specified when creating a the user in the previous step.
Each api_token is one-time use and expires in ten minutes. A fresh api_token must be requested each time a Nexus session is opened.
Open a Nexus Session
Now we're in the Nexus API, where we'll stay for the rest of the process. Use the crete session endpoint to get a session token. This session token must be sent as a header with each Nexus request relating to the given user; each Nexus session is opened in the context of a single user associated with that session token.
When using the identity endpoints, the create session request body should contain the parameter and value "skip_aggregation": true as shown in the example below. This will prevent automatic aggregation being initiated for the user's existing members when the session is opened.
Get Institution Information
Information about available institutions can be found in several ways. This example uses the search method. Most importantly, you'll use the institution GUID returned here in the next step.
Search criteria is specified in the request body; pagination is specified by appending it to the request URL.
Either a name or url must be sent in the request body for this endpoint to work properly. An empty request body will result in a 400 error.
Get the Institution's Required Credentials Using the Institution GUID
This endpoint returns information about what type of credentials the institution requires for authentication, such as a username and password, along with other important information about the credentials.
You'll use the credential GUID returned here in the next step when we create a member.
Identify a Member
The identify endpoint begins an identification process for an already-existing member. Use this endpoint when normal aggregation does not return account ownership information for the member.
The identification workflow is similar to standard aggregation: Start the identification, poll the member connection status, answer MFA if necessary by using the list member MFA challenges endpoint and the update member endpoint, poll the connection status again, then read the member's account_owners.
Poll the Member for a Change in the Connection Status
You can find more information on the various connection statuses and their associated workflows in the main docs (check out the section on members as well as the Nexus guide), but we'll give you the basics here.
A connection status of CONNECTED means that the member was successfully authenticated and identification has begun. The is_being_aggregated field will tell you whether identification has completed; the field will be true while identification is taking place and returns to false when identification is complete.
If you run into multi-factor authentication (MFA), however, you'll see a CHALLENGED connection status. In this case, you'll need to get the challenges that have been sent and answer them in order to proceed. Those steps are outlined in steps 6.2 – 6.4.
If You Run into MFA, Get the Challenges
If the connection_status returns as CHALLENGED, you'll need to answer multi-factor authentication in order to proceed. This requires calling the member challenges endpoint, the resume aggregation endpoint, and then polling the connection status again.
There are many kinds of MFA as shown in the example responses here, but the type TEXT is by far the most common.
You'll need the credential GUID provided in this response to resume the identification process in the next step.
Answer the Challenges
This endpoint allows you to respond to multi-factor authentication by providing answers to MFA challenges. Identification will automatically resume if the correct answers are provided.
You'll need to use the skip_aggregation parameter set to true in your request body to prevent an automatic standard aggregation.
Poll the Connection Status Again
Read the member again, and keep reading until the connection status becomes CONNECTED and is_being_aggregated switches to false. At that point, you can read the account owner information.
Keep in mind that MFA challenges may be issued more than once, even if a previous challenge was answered correctly. In this case, the status will return to CHALLENGED and you'll need to repeat the last few steps.
List the Member's Account Ownership Information
This endpoint will return information for all account owners gathered when you called the identify endpoint.
Keep in mind that it is possible that not every field will return with a value.
Testing Identification
MX has provided test endpoints for Identity in order for partners to test their setup without incurring the cost of calling the identify endpoint. These test endpoints return static data.
For the most robust end-to-end testing of identification, MX will need to set up test accounts for you. Please contact MX to perform this kind of testing.
In order to use the test endpoints, you must:
- Make requests through the MX integration environment; test endpoints will not function in the production environment;
- Use the following session token:
test_session; - Use the following endpoint paths:
- Get account owners (no data exists): GET
/members/unidentified/account_owners/ - Get account owners (data does exist): GET
/members/test_nexus_member/account_owners - Verify: GET
/members/test_nexus_member/identity.