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.

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"
  }
}

4. 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
  }
}