Overview

Whether you’re using the API to aggregate, to verify, or for some other use case, understanding the basic requirements for getting started is the first step.

To get started, use the following workflow:

1. Create a user.
2. Search for an institution
3. Get the institution’s required credential types.
4. Create a member.

By completing this workflow, you’re connecting your end user to their financial institution, which is required for using features like aggregation, verification, and much more. The following steps in this guide explain the flow in detail and provide example requests.

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

3. Get the Required Credential Types

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

4. Create a 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"
  }
}