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
{
"institutions": [
{
"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": 5,
"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, 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 mxuser
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": "mxuser"
},
{
"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
.