1. Create a User

The first step is to create a user. A user represents your end user in the MX Platform. Make a POST request to the create user endpoint, as shown below.

We recommend that you include a unique id of your choice with the request. You may also include metadata, such as the date the user was created or the end user’s name. Don’t include any sensitive information here, such as credentials.

In the response, the API gives each new user an MX-defined guid (or user_guid when appearing outside the user object). Between your id and the guid, you can map between your system and ours. You’ll need the user guid for nearly every request on the MX API, at least when using basic authorization.

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

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. Create a Member

2.1 Search for an Institution

After you’ve created a user, it’s time to create a member. To do so, you need to know what financial institution the member should be connected to and what type of credentials the institution expects to get.

First, search for an institution using query parameters on the list institutions endpoint.

Endpoint:

GET /institutions?name={string}

The example that follows searches for MX Bank, which is MX’s institution for testing and development.

The response returns a paginated list of institutions that match the string you send in the name query parameter. Make a note of the code you find in the example response; you’ll need this for the next step.

2.2 Get the Institution-required Credentials

Each institution requires different types of credentials. Some require an email and a password, some require a username and a password, and some may require other types of credentials.

Make a GET request to the list institution-required credentials endpoint.

Endpoint:

GET /institutions/{institution_code}/credentials

Include the institution code retrieved from the previous step in the request URL.

This endpoint returns the guid for each credential returned, which is used to match the credentials the end user provides to the required credential type in the next step.

1
2
3
curl -X GET https://int-api.mx.com/institutions/mxbank/credentials \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "credentials": [
    {
      "display_order": 1,
      "field_name": "LOGIN",
      "field_type": "LOGIN",
      "guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
      "label": "Username"
    },
    {
      "display_order": 2,
      "field_name": "PASSWORD",
      "field_type": "PASSWORD",
      "guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
      "label": "Password"
    }
  ]
}

2.3 Create the Member

After you have the user_guid, an institution_code, and a guid for each credential required by the institution, create a new member. For this step, you need the values provided by the end user for each necessary credential.

Make a POST request to the create member endpoint shown below.

Endpoint:

POST /users/{user_guid}/members

You can include the following parameters in your request.

Request

The following example uses MX Bank and therefore requires a username and a password. It sets the username to mxuser and the password to password which are the credentials for the test user for MX Bank. For real institutions, these values must be the end user’s correct login information.

Response

If the request is successful, the response returns with the newly created member and a standard aggregation is automatically kicked off. The connection_status is CREATED and the is_being_aggregated field is true.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "credentials": [
          {
            "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
            "value": "mxuser"
          },
          {
            "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
            "value": "password"
          }
        ],
        "institution_code": "mxbank"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "background_aggregation_is_disabled": false,
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

3. Verify the Member

Verification is similar to the standard aggregation process covered in the aggregation developer guide. Consult that guide for additional information, including details on how to deal with multifactor authentication.

To start the IAV process, make a POST request to the verify member endpoint.

Endpoint:

POST /users/{user_guid}/members/{member_guid}/verify

1
2
3
4
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/verify' \
-u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {
    "aggregated_at": null,
    "background_aggregation_is_disabled": false,
    "connection_status": "CREATED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_managed_by_user", true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": null
  }
}

4. Check the Connection Status

Use the read member status endpoint to get important information on the state of the IAV job. You may need to check this endpoint several times. connection_status is the important field at this point. CONNECTED means that the member was successfully authenticated and IAV has begun.

You’ll always have to answer at least one special challenge from MX to select which account to verify. When this happens, you’ll see the status switch to CHALLENGED, and the response will include the challenges you need to answer.

If you don’t get the special challenge and the member goes to directly to connection_status: CONNECTED and is_being_aggregated: false, it means that there are no eligible accounts to verify and there’s nothing more to do.

Endpoint:

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

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "is_authenticated": false,
    "is_being_aggregated": true,
    "successfully_aggregated_at": null
  }
}

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "member": {
    "aggregated_at": null,
    "challenges": [
      {
        "field_name": null,
        "guid": "CRD-bc26dc1d-9fe3-41f1-9d67-e84070cf3055",
        "label": "Please select an account:",
        "options": [
          {
            "label": "Checking",
            "value": "act-23445745"
          },
          {
            "label": "Savings",
            "value": "act-352386787"
          }
        ],
        "type": "OPTIONS"
      }
    ],
    "connection_status": "CHALLENGED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "is_authenticated": true,
    "is_being_aggregated": true,
    "successfully_aggregated_at": null
  }
}

5. Answer the Account-selection Challenge

To answer MX’s account-selection challenge, you’ll need to present the challenge from the previous step to end users, gather their response, and then give that back to MX using the resume endpoint.

5.1 Use the Resume Endpoint

Use the resume aggregation endpoint to answer the challenge. Include the appropriate credential GUID with the value chosen by the end user.

The response should come back with connection_status: RESUMED.

Endpoint:

PUT /users/{user_guid}/members/{member_guid}/resume

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/resume' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "challenges": [
          {
            "guid": "CRD-bc26dc1d-9fe3-41f1-9d67-e84070cf3055",
            "value": "act-23445745"
          }
        ]
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "member": {
    "aggregated_at": null,
    "background_aggregation_is_disabled": false,
    "connection_status": "RESUMED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "is_oauth": false,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-151a102b-90b3-1bc3-48d1-c24cad5a2b13",
    "user_id": "10405939560"
  }
}

5.2 Check the Status Again

At this point, important fields include connection_status, is_being_aggregated, and successfully_aggregated_at. The is_being_aggregated field will tell you whether the verification job has completed; it’ll be true while IAV is running and false when complete. When you see connection_status: CONNECTED and is_being_aggregated: false at the same time, the IAV job is done and you can pull account and routing data. The successfully_aggregated_at field will give the exact time the IAV job finished.

Endpoint:

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

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'

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

6. List the Account Numbers

The IAV job is now complete and you can list account and routing numbers. The MX Platform API has two endpoints for this: list account numbers by member and list account numbers by account. We show the first here.

Endpoint:

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

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/account_numbers' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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",
      "passed_validation": true,
      "transit_number": null,
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}