Introduction

Almost everything in the MX API centers around a specific user (representing the end user) and a member (representing the connection between a user and a financial institution). So, of course, these are the first things you’ll need to create in order to do anything interesting with the MX API.

Here’s a step by step guide for creating both of these important resources.

1. Create a user

Make a POST request to the create user endpoint, as shown below.

It’s a good idea to send along a unique id of your choice with your request. The API will also give each new user an MX-defined guid (or user_guid when appearing outside the user object). Between your id and the guid, you’ll easily be able to 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.

You may also include metadata, such as the date the user was created, the end user’s name, etc. Just make sure not to include any sensitive information here, like credentials.

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 -L -X POST 'https://int-api.mx.com/users' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "user": {
        "id": "unique-id-1234",
        "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-5274d346-f173-41af-a041-45594080970c",
    "id": "unique-id-1234",
    "is_disabled": false,
    "metadata": "Yada yada yada"
  }
}

2. Search for an institution

Now that you have a user to work with, it’s time to create a member. But before we can do that, we need to know what financial institution the member should be connected to. We’ll also need to find out what type of credentials the institution expects to get. These will be our next couple steps.

We’ll need to search for an institution using query parameters on the list institutions endpoint. In this case, we’re looking for MX Bank, which is MX’s institution for testing and development. You’ll get a paginated list of institutions which match the string you send in the name query parameter.

Make a note of the code you find for MX Bank in the example response below; you’ll need this for our next step.

Endpoint:

GET /institutions?name={string}

Example request

1
2
3

curl -L -X GET 'https://int-api.mx.com/institutions?name=mx' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json'

Example response

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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

{
  "institutions": [
    {
      "code": "378163771",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "Gringotts",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": true,
      "supports_account_statement": true,
      "supports_account_verification": true,
      "supports_oauth": false,
      "supports_transaction_history": true,
      "url": "https://int-gringotts.mx.com/on_demand/v5"
    },
    {
      "code": "mxbank",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-1572a04c-912b-59bf-5841-332c7dfafaef_100x100.png",
      "name": "MX Bank",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-1572a04c-912b-59bf-5841-332c7dfafaef_50x50.png",
      "supports_account_identification": true,
      "supports_account_statement": false,
      "supports_account_verification": true,
      "supports_oauth": false,
      "supports_transaction_history": true,
      "url": "https://www.mx.com"
    },
    {
      "code": "d8927e54-1aa7-331e-5060-fbee168e628c",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "MX Bank of Utah",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": false,
      "supports_account_statement": false,
      "supports_account_verification": false,
      "supports_oauth": false,
      "supports_transaction_history": false,
      "url": "https://www.mx.com"
    },
    {
      "code": "da3f211e-fd77-8e3b-e921-fee5056480cf",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-93a8780f-fb10-ebfa-cc94-4aede74f6e23_100x100.png",
      "name": "MX Credit Union",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": false,
      "supports_account_statement": false,
      "supports_account_verification": false,
      "supports_oauth": false,
      "supports_transaction_history": false,
      "url": "https://www.mx.com"
    },
    {
      "code": "2fc6472c-f837-c99d-56fb-a1644702b4cd",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
      "name": "MX Bank of Texas",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
      "supports_account_identification": false,
      "supports_account_statement": false,
      "supports_account_verification": false,
      "supports_oauth": false,
      "supports_transaction_history": false,
      "url": "https://www.mx.com"
    },
    {
      "code": "mx_bank_oauth",
      "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-68e96dd6-eabd-42d3-9f05-416897f0746c_100x100.png",
      "name": "MX Bank (Oauth)",
      "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-68e96dd6-eabd-42d3-9f05-416897f0746c_50x50.png",
      "supports_account_identification": false,
      "supports_account_statement": false,
      "supports_account_verification": false,
      "supports_oauth": false,
      "supports_transaction_history": false,
      "url": "www.mx.com"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 6,
    "total_pages": 1
  }
}

3. Get the institution's required credentials

Each institution requires different credentials. Some require an email and a password. Some require a username and a password. And some require more exotic credentials. This endpoint will give you what you need in order to move on to the next step, specifically the guid for each credential returned.

Notice too that the request URL includes the institution code you got from the previous step.

Endpoint:

GET /institutions/{institution_code}/credentials

Example request

1
2
3

curl -X GET https://int-api.mx.com/institutions/mxbank/credentials \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Authorization: Basic {token}'

Example response

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

Now that we’ve got a user_guid, an institution_code, and a guid for each credential required by the institution, so we can finally create a new member. You’ll also need the end-user-provided values for each necessary credential, in this case a username and a password.

For MX Bank, you should set the username to test_atrium and the password to password. When you move on to aggregating your new member (covered in another guide), these values will mimic a successful aggregation with no MFA. For real institutions, these values must be the end user’s correct login information.

Here’s the parameters you can include in your request.

Parameters

Parameter Data type Description Required?
background_aggregation_is_disabled Boolean When set to true, background aggregation will be disabled for this member. No
credentials Array The credentials endpoint for the requested institution will give you a list of all the credentials required to create a member for a given institution. Each required credential will need to be included within this array. Yes
id String The unique partner-defined identifier for the member. No
institution_code String The unique code for the institution to which the member will connect. Defined by MX. Yes
metadata String Additional information you can store on this member. No

Endpoint:

POST /users/{user_guid}/members

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

curl -L -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "credentials": [
          {
            "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
            "value": "test_atrium"
          },
          {
            "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
            "value": "password"
          }
        ],
        "institution_code": "mxbank"
      }
    }'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "member": {
    "aggregated_at": null,
    "connection_status": "CREATED",
    "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"
  }
}

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

Next Steps

Aggregating data

Now that you’ve created a user and a member, you can start using the really powerful features of the API like aggregation, verification, custom categories, tags, and a whole lot more.

In the next guide, we’ll take a look at aggregation, which can sometimes be complicated and depends on a number of different processes.

Go to next guide