1. List OAuth Institutions

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

Currently, there’s no 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.
  • "referral_source": "APP" tells MX to 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.

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": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2",
    "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.

oauth_window_uris are one-time use. Don’t hard code an expected URI into your application.

Don’t prepend the https:// protocol to the URI string, as MX includes this.

This is 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 client_redirect_url with appended information

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

4. Check the Member Status

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. You’ll need to check the status of that aggregation until you see the correct combination of values: connection_status must be CONNECTED, is_aggregating must be false, and successfully_aggregated_at must be updated to the current time. When you see this combination, aggregation is complete and you can move 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

First, get a list of all the account data associated with your user.

You can see in the following example that the user has 21 accounts associated with it. If you look at the type field, there is a checking account, a savings account, a credit card account, and several others. Also, there is information on the balance of each account, such as APY for credit accounts or payment due days. 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 the list transaction by account endpoint. Notice from the pagination object in the response that there are 176 transactions in this account and that the endpoint returned the first 25 of these.

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

You can access the rest of these transactions by making another request and specifying the number of records you want to access (valid values range between 10 and 100) and specifying the page you’d like to see. You can pass these parameters in the request URL to same endpoint as demonstrated in the following example. The pagination object in the response now shows 100 records per page and a current page of 2.

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

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.

Next Steps

Now that you’ve seen the account and transaction data you’ve aggregated, you can explore other features of the API like accessing investment data, using premium features like account identification and verification, and more.

View the API reference