Tax Documents Step-By-Step
Prerequisites
- 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.
- This guide uses the MX Widget SDK. See Implementation Guides to install and set up an SDK before getting started with tax documents.
- The endpoints in this guide are available in our Platform API wrapper libraries.
Create a user
A user represents your end user in the MX Platform. Make a request to the Create User endpoint (POST /users).
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.
None of these parameters are required, but the user object can't be empty. We recommend that you always set the id parameter when creating a user.
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.
Request a Connect Widget URL
Make a POST request to the /users/{user_guid}/widget_urls endpoint
- Set the
modeparameter totax. - Set the
widget_typeparameter toconnect_widget. - Set the
disable_background_aggparameter totrue. This is necessary to prevent daily standard aggregations from interfering with tax document aggregations.
Setting the mode to tax limits Connect Widget search results to institutions that support tax documents.
Widget URLs are one-time use. You must fetch a new widget URL each time you load the widget.
Load the URL and Let The End User Interact
Load the URL in your application or website. At this point the end user will interact with the Connect Widget. The widget handles the creation of a member as well as the tax process and any MFA that may be encountered. It automatically asks end users to search for an institution, give their credentials, or authenticate with OAuth. It also deals with any errors along the way.
You'll need to listen for a couple important event messages from the Connect Widget:
- member status updated which gives you the member GUID and the current
connection_status. - member connected tells you that the member has been successfully connected and you can move on to the next steps.
Alternatively, if the end user closes the Connect Widget early or some other problem occurs before you see a CONNECTED status, you can use the member_guid to immediately check the member's connection status with a dedicated API endpoint.
List the 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.
If you already have the guid for a particular tax document, you may also choose to read the details for that particular document rather than list all available.
GET users/{user_guid}/members/{member_guid}/tax_documents/{tax_document_guid}
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.
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.
6.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 endpoint may trigger multi-factor authentication that requires end-user input.
6.2 Check the Member's Status
Check the connection status of the member to get information on the state of the tax docs aggregation. Important fields include connection_status, is_being_aggregated, and successfully_aggregated_at. The is_being_aggregated field will tell you whether the tax docs aggregation is ongoing or complete.
When you see "connection_status": "CONNECTED" and "is_being_aggregated": false at the same time, the tax docs aggregation is done and you can move on to the next step. The successfully_aggregated_at field will give the exact time the aggregate successfully completed, but won't update if the tax docs aggregation fails.
You may need to check the connection status several times until an end state is reached.
Make a request to the Read Member Status endpoint (GET /users/{user_guid}/members/{member_guid}/status). The response in the example shows a successful end state.
6.3 List, Read, or Download Tax Docs
Once a successful end state is reached, you may list, read, or download tax documents.