Introduction

Some financial institutions allow developers to access an end user’s tax documents. The process for fetching and then reading tax documents is much like standard aggregation. The preferred method is to use the Connect widget to aggregate tax documents and download them with the Platform API.

The general workflow is as follows:

  1. Create a user.
    • Capture the user’s guid.
  2. Request a Connect widget URL with the correct configuration for tax docs.
  3. Load and interact with the Connect widget using one of our SDKs.
    • The end user follows the Connect widget flow which allows them to select an institution, create a member, and aggregate tax documents.
  4. After the end user completes the Connect widget flow, capture the member_guid from the memberConnected postMessage event.
  5. Interact with the aggregated tax documents.
    • This may be retrieving a list of available documents, reading information about a specific document, or downloading a PDF of a document.
  6. If necessary, fetch the latest tax documents again using the API.

Prerequisites

  1. Before you begin, make sure you’ve done everything on our checklist for success.
  2. Be aware that tax document features can only be tested in our production environment. This means you will need to request and obtain production access before getting started with tax documents.
  3. This guide uses the MX Widget SDK. Make sure to read the guide to install and set up the SDK before getting started with tax documents.
  4. The endpoints in this guide are available in our Platform API wrapper libraries.

1. Create a User

The first step is to create a user. A user represents the end user on 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 (such as credentials) in the metadata. In the response, you’ll get 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 when loading the Connect widget.

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

curl -i -X POST 'https://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. Request a Connect Widget URL

Make a POST request to the /users/{user_guid}/widget_urls endpoint. The response will include a url which you’ll need to capture for the next step.

  • Use the path’s user_guid to the value obtained in step 1.
  • Set the mode to tax.
  • Set the widget_type to connect_widget.
  • Set disable_background_agg to true. This is necessary to prevent daily standard aggregations from interfering with tax document aggregations.
1
2
3
4
5
6
7
8
9
10
11
12

curl -i -X POST 'https://api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -u 'client_id:api_key' \
  -H 'Content-type: application/json' \
  -d '{
        "widget_url": {
          "current_institution_code": "wells_fargo",
          "disable_background_agg": "true",
          "mode": "tax",
          "widget_type": "connect_widget"
        }
      }'

1
2
3
4
5
6
7

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "partner-2345"
  }
}

3. Use an SDK to Load the Connect Widget

The preferred method for loading a specific instance of the Connect widget is using one of our SDKs. We maintain a web SDK and a React Native SDK. Follow the steps in one of these SDK guides. You’ll use the url you captured in step 2.

4. End Users and the memberConnected Event

Once end users are presented with the Connect widget, they’ll be taken through the widget flow which includes getting end-user credentials, dealing with multifactor authentication, and dealing with errors. On the back end, the widget will create a member and aggregate all tax documents associated with that member’s accounts.

After a member is successfully created and aggregated, the Connect widget will issue a memberConnected postMessage event. This means tax document data is ready to be accessed. The payload of this message will contain a member guid which you’ll need to capture for use in the next step. More information on how to do this can be found in the web SDK and React Native SDK guides.

5. List Available Tax Docs

Make a GET request to the /users/{user_guid}/members/{member_guid}/tax_documents endpoint. The response will include a paginated list of all tax documents available to download for the specified user and member, along with data about each document. This data includes a guid which can be used to read the data about that specific document, and a uri, which can be used to download a PDF version of the document. For more information on tax document fields, see our reference page.

  • Set the path’s user_guid to the value obtained in step 1.
  • Set the path’s member_guid to the value obtained in step 4.
1
2
3

curl -i -X GET 'https://api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/tax_documents' \
  -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

{
  "tax_documents": [
    {
      "content_hash": "a16c580c4fcdfa8088edaa7b4d35b290",
      "created_at": "2022-10-18T19:23:16Z",
      "document_type": "TAX_MISC",
      "guid": "TAX-ee8776ea-468b-4b02-b95d-743adf6ba50e",
      "issued_on": "2022-03-31",
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "tax_year": "2022",
      "updated_at": "2022-10-18T19:23:16Z",
      "uri": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/tax_documents/TAX-ee8776ea-468b-4b02-b95d-743adf6ba50e.pdf",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    },
    {
      "content_hash": "067b2c789bf830fcc8460203ffd3efc0",
      "created_at": "2022-10-18T19:23:25Z",
      "document_type": "TAX1099_R",
      "guid": "TAX-a2fc5fbd-fc1d-42d5-8894-7fe8a68d5aaa",
      "issued_on": "2021-12-31",
      "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "tax_year": "2021",
      "updated_at": "2022-10-18T19:23:25Z",
      "uri": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/tax_documents/TAX-a2fc5fbd-fc1d-42d5-8894-7fe8a68d5aaa.pdf",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_entries": 2,
    "total_pages": 1
  },
}

6. Read Data About a Tax Doc

Make a GET request to the /users/{user_guid}/members/{member_guid}/tax_documents/{tax_document_guid} endpoint. The response will have data about the specified document. For more information on tax document fields, see our reference page.

  • Set the path’s tax_document_guid to a value from step 5.
1
2
3

curl -i -X GET 'https://api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/tax_documents/TAX-ee8776ea-468b-4b02-b95d-743adf6ba50e' \
  -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

{
  "tax_document": {
    "content_hash": "a16c580c4fcdfa8088edaa7b4d35b290",
    "created_at": "2022-10-18T19:23:16Z",
    "document_type": "TAX_MISC",
    "guid": "TAX-ee8776ea-468b-4b02-b95d-743adf6ba50e",
    "issued_on": "2022-03-31",
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "tax_year": "2022",
    "updated_at": "2022-10-18T19:23:16Z",
    "uri": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/tax_documents/TAX-ee8776ea-468b-4b02-b95d-743adf6ba50e.pdf",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

7. Download a Tax Doc PDF

Make a GET request to the /users/{user_guid}/members/{member_guid}/tax_documents/{tax_document_guid}.pdf endpoint. The API responds with the bytes of a PDF version of the tax document.

  • This endpoint is the same as the uri field on a given tax_document.
1
2
3
4

curl -i -X GET 'https://api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/tax_documents/TAX-ee8776ea-468b-4b02-b95d-743adf6ba50e.pdf' \
  -H 'Accept: application/vnd.mx.api.v1+pdf' \
  -u 'client_id:api_key' \
  --output TAX-ee8776ea-468b-4b02-b95d-743adf6ba50e.pdf

1
2

# This endpoint responds with the
# bytes of the PDF file.

8. Fetch Tax Docs at a Later Time

It may be necessary to get the latest tax documents for a user from time to time. This is a multi-step process using API endpoints.

8.1 Start the Fetch Job

Make a POST request to the /user/{user_guid}/member/{member_guid}/fetch_tax_documents endpoint.

This request does not return the latest tax documents. It just starts the document aggregation process and returns the initial state of the process. You must interact with the newly aggregated data using the endpoints described above after the process is complete. This request may also trigger multi-factor authentication which requires end-user input and a specific process for answering authentication challenges.

1
2
3
4

curl -i -X POST 'https://api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/fetch_tax_documents' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key'

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

{
  "member": {
    "aggregated_at": "2022-10-13T18:07:57Z",
    "background_aggregation_is_disabled": true,
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "id": null,
    "institution_code": "wells_fargo",
    "is_being_aggregated": true,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "Yada yada yada",
    "name": "Wells Fargo",
    "successfully_aggregated_at": "2022-10-13T17:57:38Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "partner-2345"
  }
}

8.2 Poll the Member's Status

To check on the status of the tax documents job, poll the status until an end state is reached.

Make a GET request to the /user/{user_guid}/member/{member_guid}/status endpoint. The response will describe the current state of the tax document job for the member.

A successful job is complete when:

  • The is_being_aggregated field switches from true to false.
  • The connection_status is CONNECTED.
  • The successfully_aggregated_at field updates to the current time.

Once this state is reached, you can interact with tax documents using the read, list, and download endpoints.

1
2
3

curl -i -X GET 'https://api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/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

{
  "member": {
    "aggregated_at": "2022-12-14T18:49:13Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4",
    "has_processed_account_numbers": false,
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2022-12-14T18:49:17Z"
  }
}