OAuth overview, prerequisites, and workflows

OAuth is a simple, secure, and standardized way to perform authentication without actually exchanging sensitive credentials like usernames and passwords. Actually, you probably already know that since you’re here trying to leverage MX’s support for this ubiquitous protocol. But if you’d like to learn more about it in general, you can check out the official website or Wikipedia.

What you’ll learn in this guide is how to properly deal with OAuth while coding up to the MX Platform API, whether you’re developing for the browser or a mobile app. As a side note, if you’re using our ready-made Connect widget for creating members on the MX platform, you’re in luck, because it deals with OAuth more or less automatically. We’ve got separate guides for partners using Connect.


Registration and production access

First is that you can’t just use OAuth with any institution — some institutions support OAuth, some don’t. On the other hand, some institutions only support OAuth, and you won’t be able to authenticate using ordinary credentials.

Second, before you can use OAuth, you’ll have to register with the financial institution. This registration process is what provides the tokens required for a successful and secure authentication. MX will handle all these registrations for you, but you’ll only be able to do this once MX has granted you production access to the Platform API. You can request request production access and apply for OAuth registration on the dashboard.

One important consequence of all this is that there is only one OAuth institution available in the integrations environment: mx_bank_oauth, which is one of our test institutions. It will behave just like any other OAuth institution, and it does not require registration. Hence, everything you’ll see in this guide will be using this test institution.


OAuth workflows

Here’s the basic outline of the OAuth aggregation flow.

  1. List the institutions and find those that support OAuth;
    • In the integrations environment, you must always use mx_bank_oauth.
  2. Create an OAuth member with "is_oauth": true;
    • If you’re developing a mobile app, you’ll also need to set "oauth_referral_source": "APP" and "client_redirect_url": "your://custom.redirect/url"; you can set the redirect URL to any string, but we’ll use https://mx.com in this guide.
  3. Load the oauth_window_uri returned when you create a member;
    • You must open this URI in the device’s default browser;
    • The end user will interact with the institution’s OAuth page and decide what data to share with MX.
    • If successful, aggregation will automatically begin.
  4. Check the member’s status, and keep checking until you see an end state;
    • If you see "connection_status": "CONNECTED", "is_aggregating": false and the successfully_aggregated_at field has updated to the current time, the aggregation is complete.
  5. Get the user’s account and transaction data.

Workflow diagrams

Browser

Platform API OAuth workflow — browser

Mobile app

Platform API OAuth workflow — mobile app


OAuth in mobile apps


1. List OAuth institutions

First, we’ll need to get a list of institutions that support OAuth.

There is not currently a way to search specifically for OAuth institutions, but you can do one of two things:

  • Pull down a list of all institutions and search for those with the attribute "supports_oauth": true on your end. This list could be cached as well — in fact its not a bad idea to cache the entire list of institutions, just remember to update it regularly as there are always new institutions being added.
  • If you already know which institution you’re looking for, use the name query string parameter to search for it with an API request.

This second option is shown below using MX Bank. You’ll see a couple institutions in this response, and you’ll see that the one with institution code mx_bank_oauth has the appropriate attribute. So that’s what we’ll use in the next step.

Endpoint:

GET /institutions

1
2
3
curl -X GET https://int-api.mx.com/institutions?name=mx \
  -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
29
30
31
32
33
34
35
36
{
  "institutions": [
    {
      "code": "mxbank",
      "instructional_text": null,
      "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": "mx_bank_oauth",
      "instructional_text": null,
      "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": true,
      "supports_account_statement": false,
      "supports_account_verification": true,
      "supports_oauth": true,
      "supports_transaction_history": false,
      "url": "www.mx.com"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

2. Create a member

Now we’ll need to create an OAuth member, which you can do by setting the following:

  • "is_oauth": true.
  • client_redirect_url so we can send you UI messages with the right scheme. This can be any string, but we’ll use https://mx.com in this guide.
  • "oauth_referral_source": "APP" tells MX to actually use the client_redirect_url you provided so you can get back to your app.

Remember that you cannot include end-user credentials in your request body when creating an OAuth member. The idea is to never share those with a third party at all. So this request is a little bit simpler than with other kinds of members.

Also, we recommend that you always include a unique id when creating any resource on the Platform API so you can easily sync between your systems and ours.

Endpoint:

POST /users/{user_guid}/members

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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.v2+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "id": "unique_id",
        "institution_code": "mx_bank_oauth",
        "is_oauth": true,
        "metadata": "Additional information"
      },
      "referral_source": "APP",
      "client_redirect_url": "https://mx.com"
    }'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {
    "aggregated_at": null,
    "connection_status": "PENDING",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "id": "unique_id",
    "institution_code": "mx_bank_oauth",
    "is_being_aggregated": false,
    "is_managed_by_user": true,
    "is_oauth": true,
    "metadata": "Additional information",
    "name": "MX Bank (Oauth)",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false",
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "unique_user_id",
  }
}

3. Load the OAuth URI

Now that you’ve got the oauth_window_uri from the last step, load it in the device’s default browser.

We’ll remind you that it’s here where the user will interact with the institution’s OAuth page and determine what data will be shared with MX, and therefore with you. Once the end user is done, they will be redirected to the URL you gave for client_redirect_url. We’ll append to this URL information about success/error as well as the member GUID.

Example redirect URL with appended information

https://mx.com?status=success&member_guid=MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f

4. Check the member's status until aggregation is finished

Now that the user has granted access to their data on the institution’s OAuth page and they’ve been redirected back to your app, an automatic aggregation will start. Therefore, you’ll need to check the status of that aggregation. You’ll need to keep checking this status until you see the correct combination of values. connection_status must be CONNECTED, is_aggregating must be false, and successfully_aggregated_at has updated to the current time. When you see this combination, aggregation is complete and you can move on to the next step.

Aggregation is not complete

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/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
{
  "member": {
    "aggregated_at": "2022-02-02T13:15:14Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "has_processed_accounts": false,
    "has_processed_transactions": false,
    "is_authenticated": true,
    "is_being_aggregated": true,
    "successfully_aggregated_at": null
  }
}

Aggregation is complete

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/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
{
  "member": {
    "aggregated_at": "2022-02-02T13:15:14Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "has_processed_accounts": true,
    "has_processed_transactions": true,
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2022-02-02T20:24:48Z"
  }
}

5. List account data

Let’s get a list of all the account data associated with your user.

You can see in the example below that the user has 21 accounts associated with it. If you look at the type field, you’ll see there is a checking account, a savings account, a credit card account, and several others. You’ll also see that there is information on the balance of each account, APY for credit accounts, payment due days, and a lot more. You won’t always get values for every field; that depends on the data provider and the information available from the financial institution in question.

Make a note of the account GUID for the checking account associated with our test member: ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530. We’ll need this to list all the transactions associated with the account.

Endpoint:

GET /users/{user_guid}/accounts

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
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
{
    "accounts": [
      {
        "account_number": "708191771",
        "apr": null,
        "apy": null,
        "available_balance": 1000,
        "available_credit": null,
        "balance": 1000,
        "cash_balance": null,
        "cash_surrender_value": null,
        "created_at": "2020-09-21T19:43:44Z",
        "credit_limit": null,
        "currency_code": null,
        "day_payment_is_due": null,
        "death_benefit": null,
        "guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
        "holdings_value": null,
        "id": "act-223434333",
        "institution_code": "mxbank",
        "interest_rate": null,
        "is_closed": false,
        "is_hidden": false,
        "last_payment": null,
        "last_payment_at": null,
        "loan_amount": null,
        "matures_on": null,
        "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
        "minimum_balance": null,
        "minimum_payment": null,
        "name": "Checking",
        "original_balance": null,
        "payment_due_at": null,
        "payoff_balance": null,
        "started_on": null,
        "subtype": null,
        "total_account_value": null,
        "type": "CHECKING",
        "updated_at": "2020-09-21T19:52:04Z",
        "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
      },
        •••
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 25,
        "total_entries": 21,
        "total_pages": 1
    }
}

6. List transaction data

With the account GUID you found in the last step, make a request to list the transactions for the account.

Endpoint:

GET /users/{user_guid}/accounts/{account_guid}/transactions

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530/transactions' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
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
{
  "transactions": [
    {
      "category": "Gas",
      "category_guid": "CAT-b6d63a19-30a7-e852-2703-bdfb4072289e",
      "created_at": "2020-09-21T19:43:48Z",
      "date": "2020-09-21",
      "posted_at": "2020-09-22T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Auto & Transport",
      "transacted_at": "2020-09-21T12:00:00Z",
      "type": "DEBIT",
      "updated_at": "2020-09-21T19:43:51Z",
      "account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
      "amount": 7.29,
      "check_number_string": null,
      "currency_code": "USD",
      "description": "ExxonMobil",
      "guid": "TRN-822b443e-972c-431e-8dcf-c2b08de21136",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
      "memo": null,
      "merchant_category_code": 0,
      "merchant_guid": "MCH-dcd9bbcd-11bb-076a-60c4-90f1101b3372",
      "original_description": "ExxonMobil",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    },
    •••
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 176,
    "total_pages": 8
  }
}

Notice from the pagination object that there are 176 transactions in this account and that the endpoint returned the first 25 of these. You can access the rest of the transactions by making another request and specifying the number of records you want to access (valid values range between 10 and 100) and/or specifying the page you’d like to see. You can pass these parameters in the request URL to endpoint.

Endpoint:

GET /users/{user_guid}/accounts/{account_guid}/transactions?records_per_page={value}&page={value}

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530/transactions?records_per_page=100&page=2' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
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
{
  "transactions": [
    {
      "category": "Paycheck",
      "category_guid": "CAT-982ea9e6-3f0e-0c5b-611b-6657a10ba819",
      "created_at": "2020-09-21T19:43:48Z",
      "date": "2020-07-31",
      "posted_at": "2020-08-01T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Income",
      "transacted_at": "2020-07-31T12:00:00Z",
      "type": "CREDIT",
      "updated_at": "2020-09-21T19:43:51Z",
      "account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
      "amount": 23.57,
      "check_number_string": null,
      "currency_code": "USD",
      "description": "Paycheck",
      "guid": "TRN-27b176b7-5941-42a4-8085-cfa6657f6dff",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": false,
      "is_fee": false,
      "is_income": true,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
      "memo": null,
      "merchant_category_code": 0,
      "merchant_guid": null,
      "original_description": "Payroll",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    },
    •••
  ],
  "pagination": {
    "current_page": 2,
    "per_page": 100,
    "total_entries": 176,
    "total_pages": 2
  }
}

The pagination object now shows 100 records per page and a current page of 2.

There are several other endpoints that can give you access to transaction data: list transactions by user and list transactions by member. These work in the same way as the list transactions by account endpoint described above.


OAuth in browsers


1. List OAuth institutions

First, we’ll need to get a list of institutions that support OAuth.

There is not currently a way to search specifically for OAuth institutions, but you can do one of two things:

  • Pull down a list of all institutions and search for those with the attribute "supports_oauth": true on your end. This list could be cached as well — in fact its not a bad idea to cache the entire list of institutions, just remember to update it regularly as there are always new institutions being added.
  • If you already know which institution you’re looking for, use the name query string parameter to search for it with an API request.

This second option is shown below using MX Bank. You’ll see a couple institutions in this response, and you’ll see that the one with institution code mx_bank_oauth has the appropriate attribute. So that’s what we’ll use in the next step.

Endpoint:

GET /institutions

1
2
3
curl -X GET https://int-api.mx.com/institutions?name=mx \
  -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
29
30
31
32
33
34
35
36
{
  "institutions": [
    {
      "code": "mxbank",
      "instructional_text": null,
      "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": "mx_bank_oauth",
      "instructional_text": null,
      "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": true,
      "supports_account_statement": false,
      "supports_account_verification": true,
      "supports_oauth": true,
      "supports_transaction_history": false,
      "url": "www.mx.com"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

2. Create a member

Now we’ll need to create an OAuth member, which you can do by setting the following: "is_oauth": true.

Remember that you cannot include end-user credentials in your request body when creating an OAuth member. The idea is to never share those with a third party at all. So this request is a little bit simpler than with other kinds of members.

Also, we recommend that you always include a unique id when creating any resource on the Platform API so you can easily sync between your systems and ours.

Endpoint:

POST /users/{user_guid}/members

1
2
3
4
5
6
7
8
9
10
11
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.v2+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "institution_code": "mx_bank_oauth",
        "id": "unique_id",
        "is_oauth": true
      }
    }'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {
    "aggregated_at": null,
    "connection_status": "PENDING",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "id": "unique_id",
    "institution_code": "mx_bank_oauth",
    "is_being_aggregated": false,
    "is_managed_by_user": true,
    "is_oauth": true,
    "metadata": "Additional information",
    "name": "MX Bank (Oauth)",
    "oauth_window_uri": "int-widgets.moneydesktop.com/oauth/predirect_to/MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f/p8v7rxpxg3pdAsfgwxcrwxwhz3Zbygxfr6wAb931qv91hpb57k6bkr6t6m9djrfrfd467p8xkgqp6w7k1r9g8k8bfxqbfw2lq5tdwjq2sngAx76fm0jrw0dpmbtlkxchgjsw3r7r0hhq6A8sshqptfxql2rt123shfpkyhhpfvy67yvprbkb7lmlyrpwsd9yj0s22pmsyjhcw7d2q44d9fsxn5kfsmr2zqc79c2AxAx5gkjgbczf22A1sjx70t2pvnggzyh55s7bh62dd5wq7f1r4x90mcxn1tfhhrq5b09mjkt5hg66cjn700pcf6fgA42lbsp7v1pdch85mswycrp21c6j2sxffm14Asg3?skip_aggregation=false",
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "unique_user_id",
  }
}

3. Load the OAuth URI

Now that you’ve got the oauth_window_uri from the last step, load it for the end user.

We’ll remind you that it’s here where the user will interact with the institution’s OAuth page and determine what data will be shared with MX, and therefore with you. Once the end user is done, you’ll need to get the user back to the appropriate place on your website.


4. Check the member's status until aggregation is finished

Now that the user has granted access to their data on the institution’s OAuth page and they’ve been redirected back to your app, an automatic aggregation will start. Therefore, you’ll need to check the status of that aggregation. You’ll need to keep checking this status until you see the correct combination of values. connection_status must be CONNECTED, is_aggregating must be false, and successfully_aggregated_at has updated to the current time. When you see this combination, aggregation is complete and you can move on to the next step.

Aggregation is not complete

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/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
{
  "member": {
    "aggregated_at": "2022-02-02T13:15:14Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "has_processed_accounts": false,
    "has_processed_transactions": false,
    "is_authenticated": true,
    "is_being_aggregated": true,
    "successfully_aggregated_at": null
  }
}

Aggregation is complete

1
2
3
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/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
{
  "member": {
    "aggregated_at": "2022-02-02T13:15:14Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "has_processed_accounts": true,
    "has_processed_transactions": true,
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2022-02-02T20:24:48Z"
  }
}

5. List account data

Let’s get a list of all the account data associated with your user.

You can see in the example below that the user has 21 accounts associated with it. If you look at the type field, you’ll see there is a checking account, a savings account, a credit card account, and several others. You’ll also see that there is information on the balance of each account, APY for credit accounts, payment due days, and a lot more. You won’t always get values for every field; that depends on the data provider and the information available from the financial institution in question.

Make a note of the account GUID for the checking account associated with our test member: ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530. We’ll need this to list all the transactions associated with the account.

Endpoint:

GET /users/{user_guid}/accounts

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
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
{
    "accounts": [
      {
        "account_number": "708191771",
        "apr": null,
        "apy": null,
        "available_balance": 1000,
        "available_credit": null,
        "balance": 1000,
        "cash_balance": null,
        "cash_surrender_value": null,
        "created_at": "2020-09-21T19:43:44Z",
        "credit_limit": null,
        "currency_code": null,
        "day_payment_is_due": null,
        "death_benefit": null,
        "guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
        "holdings_value": null,
        "id": "act-223434333",
        "institution_code": "mxbank",
        "interest_rate": null,
        "is_closed": false,
        "is_hidden": false,
        "last_payment": null,
        "last_payment_at": null,
        "loan_amount": null,
        "matures_on": null,
        "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
        "minimum_balance": null,
        "minimum_payment": null,
        "name": "Checking",
        "original_balance": null,
        "payment_due_at": null,
        "payoff_balance": null,
        "started_on": null,
        "subtype": null,
        "total_account_value": null,
        "type": "CHECKING",
        "updated_at": "2020-09-21T19:52:04Z",
        "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
      },
        •••
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 25,
        "total_entries": 21,
        "total_pages": 1
    }
}

6. List transaction data

With the account GUID you found in the last step, make a request to list the transactions for the account.

Endpoint:

GET /users/{user_guid}/accounts/{account_guid}/transactions

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530/transactions' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
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
{
  "transactions": [
    {
      "category": "Gas",
      "category_guid": "CAT-b6d63a19-30a7-e852-2703-bdfb4072289e",
      "created_at": "2020-09-21T19:43:48Z",
      "date": "2020-09-21",
      "posted_at": "2020-09-22T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Auto & Transport",
      "transacted_at": "2020-09-21T12:00:00Z",
      "type": "DEBIT",
      "updated_at": "2020-09-21T19:43:51Z",
      "account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
      "amount": 7.29,
      "check_number_string": null,
      "currency_code": "USD",
      "description": "ExxonMobil",
      "guid": "TRN-822b443e-972c-431e-8dcf-c2b08de21136",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
      "memo": null,
      "merchant_category_code": 0,
      "merchant_guid": "MCH-dcd9bbcd-11bb-076a-60c4-90f1101b3372",
      "original_description": "ExxonMobil",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    },
    •••
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 176,
    "total_pages": 8
  }
}

Notice from the pagination object that there are 176 transactions in this account and that the endpoint returned the first 25 of these. You can access the rest of the transactions by making another request and specifying the number of records you want to access (valid values range between 10 and 100) and/or specifying the page you’d like to see. You can pass these parameters in the request URL to endpoint.

Endpoint:

GET /users/{user_guid}/accounts/{account_guid}/transactions?records_per_page={value}&page={value}

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530/transactions?records_per_page=100&page=2' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
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
{
  "transactions": [
    {
      "category": "Paycheck",
      "category_guid": "CAT-982ea9e6-3f0e-0c5b-611b-6657a10ba819",
      "created_at": "2020-09-21T19:43:48Z",
      "date": "2020-07-31",
      "posted_at": "2020-08-01T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Income",
      "transacted_at": "2020-07-31T12:00:00Z",
      "type": "CREDIT",
      "updated_at": "2020-09-21T19:43:51Z",
      "account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
      "amount": 23.57,
      "check_number_string": null,
      "currency_code": "USD",
      "description": "Paycheck",
      "guid": "TRN-27b176b7-5941-42a4-8085-cfa6657f6dff",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": false,
      "is_fee": false,
      "is_income": true,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
      "memo": null,
      "merchant_category_code": 0,
      "merchant_guid": null,
      "original_description": "Payroll",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    },
    •••
  ],
  "pagination": {
    "current_page": 2,
    "per_page": 100,
    "total_entries": 176,
    "total_pages": 2
  }
}

The pagination object now shows 100 records per page and a current page of 2.

There are several other endpoints that can give you access to transaction data: list transactions by user and list transactions by member. These work in the same way as the list transactions by account endpoint described above.