1. Create a user

Verification using Connect combines requests to the MX Platform API with our simple and elegant widget. This widget is designed to make the complicated verification and aggregation processes easy for both you as a partner and for end users. It takes care of searching for institutions, gathering credentials, creating and connecting a member, and dealing with common errors.

But before we get to all that, you’ll need to create a new user. We’ve already got a detailed guide on creating users and members as well as a technical reference, and really, this step is pretty simple, so there’s not much more to say. Just check out the examples below.

Parameters

Field Data type Required?
email String No
id String No
is_disabled Boolean No
metadata String No

Endpoint:

POST /users

Example request

1
2
3
4
5
6
7
8
9
10
11
12
curl -i -X POST 'https://int-api.mx.com/users' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "user": {
        "id": "partner-2345",
        "is_disabled": false,
        "email": "totally.fake.email@notreal.com",
        "metadata": "Yada yada yada"
      }
    }'

Example response

1
2
3
4
5
6
7
8
9
{
  "user": {
    "email": "totally.fake.email@notreal.com",
    "guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "id": "partner-2345",
    "is_disabled": false,
    "metadata": "Yada yada yada"
  }
}

2. Load the connect widget in verification mode

Next, you’ll want to load an instance of the Connect widget using the unique user GUID returned in the last request.

There are all kinds of ways to configure the Connect widget — which you can check out in our reference or detailed guide — but the main thing to note here is that the mode parameter must be set to verification and the widget_type parameter must be set to connect_widget, as in the example below.

For more information on actually embedding a widget into a web page or in a mobile WebView, see the reference and guide linked above.

Endpoint:

POST /users/{user_guid}/widget_urls

Example request

1
2
3
4
5
6
7
8
9
10
11
curl -i -X POST 'https://int-api.mx.com/users/USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2/widget_urls' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "color_scheme": "dark",
        "mode": "verification"
      }
    }'

Example response

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "partner-2345"
  }
}

3. End users enter their credentials and launch a verification job

Connect handles the creation of a member as well as the verification and MFA processes. It automatically asks end users to search for an institution, give credentials, determine which specific account they’d like to verify, and deal with any errors along the way.

With all this in mind, you’ll need to listen for a couple important event messages from Connect: member status update and member connected. The first will give you the member_guid and the current connection_status which will give you an idea of what’s happening with connection process; the second will tell you when the member has been successfully connected so you can move on to the next steps. If your implementation uses WebViews, you’ll need to listen for the same messages, but given through the postMessage alternative for WebViews.

Alternatively, if the end user closes Connect early or some other problem occurs before you see a CONNECTED status, you can simply use the member_guid to immediately check the member’s connection status as shown in step 4.


4. Poll the connection status

So, you’ve got an event message indicating that the member is now connected and the Connect UI has closed. However, that does not mean that the verification job is finished. It just means that the connection has been established — the process of gathering the account and routing numbers may still be ongoing.

That’s why we need to poll the member status endpoint and look at all the fields there to determine when the process is finished. This can sometimes be complicated, but the easy-mode answer is that the connection_status field will be CONNECTED and the is_being_aggregated field will be false. At this point, you can be confident the process is finished and move on to listing the account and routing numbers. The successfully_aggregated_at field will give you the exact time the verification job finished.

You may need to poll this endpoint several times before an end state is reached.

Detailed information on the various fields and statuses you may run into can be found in our reference on members.

You may also want to consider the wait_for_full_aggregation option when loading Connect in step 2 above. If implemented properly, Connect will stay open to the end user until the verification process is entirely complete, meaning all data has been gathered before Connect closes.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/status

Example request

1
2
3
curl -i 'https://int-api.mx.com/users/USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'

Example response

1
2
3
4
5
6
7
8
9
10
{
  "member": {
    "aggregated_at": "2020-05-07T22:01:00Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2020-05-07T22:01:25Z"
  }
}

5. List the account and routing numbers for the member

Now that the verification is complete and data has been gathered, it’s time to actually read that data. The MX Platform API has two endpoints for this: list account numbers by member and list account numbers by account. We’re only going to show the first endpoint here because using the latter requires you to know the account GUID you’re looking for, which requires an extra step — we’re trying to keep things as easy as possible for this guide.

This request is dead simple and returns a list of all the account and routing numbers just gathered for the member.

If MX has both an account number and a routing number for at least one of the member’s accounts, that information will be returned. No information will be returned for accounts that are missing a value for one or both of these fields.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/account_numbers

Example request

1
2
3
curl -i 'https://int-api.mx.com/users/USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/account_numbers' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "account_numbers": [
    {
      "account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
      "account_number": "10001",
      "institution_number": null,
      "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
      "routing_number": "68899990000000",
      "transit_number": null,
      "user_guid": "USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}