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:
- Create a user.
- Search for an institution
- Get the institution’s required credential types.
- 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.
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 |
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"
}
}