mintapi

An unofficial screen-scraping API for Mint.com.

mintapi scrapes Mint.com by using Selenium/WebDriver to navigate a browser. Once logged in, mintapi allows programatic, automated access to Mint's UI.

IMPORTANT: mintapi 2.0 vs 1.x and breaking changes

We recently released 2.0, which supports (and only supports) the new Mint UI:

If your account has the new UI with the nav on the left, you'll need to install at least 2.0: pip install mintapi>=2.0
If your account still has the original UI with the nav on top, to use 2.0, you will need to specify --beta in your command-line options or submit beta=True when initializing the class. Otherwise, please install the latest 1.x release: pip install mintapi<2.0

Please note that due to data changes on the Mint.com side as well as various new features and changes on the mintapi side, there are several breaking changes in 2.0. Please see the CHANGELOG for details.

Installation

Install with pip from PyPi

pip install mintapi

Or for the latest release:

pip install git+https://github.com/mintapi/mintapi

Then simply:

mintapi --keyring --headless you@example.com

You will be prompted for your password, which will be stored securely in your system keyring, and use a headless (invisible) browser to log in and grab the account data. If this triggers an MFA prompt, you'll be prompted for the one-time code on the command line. MFA prompts default to SMS unless you specify --mfa-method=email. mintapi persists the browser session in $HOME/.mintapi/session to avoid an MFA in the future, unless you specify --session-path=None.

To simplify CLI invocation, you can specify a configuration file with the --config-file argument. For arguments such as --transactions, you can add a line in your config file that says transactions. For other arguments that have input, such as --start-date, you would add a line such as start-date=10/01/21. Reading email and password from config files is not supported. You must pass them as arguments directly or through a keyring.

For help, or just to chat with fellow mintapi users, please join us on Discord! :)

Complete Setup

MFA Authentication Methods

Mint accepts MFA in one of four ways: text, voice, email, or TOTP (Time-based One-Time Password). mintapi supports all of these options except Voice.

While you may disable MFA altogether, doing so is not recommended. Not only will it decrease your account security, but Mint will sometimes still email you a second factor code. So, for the least fragility, enable MFA.

As of v2.0, the mfa_method parameter is only required when using soft-token, or if your login flow presents you with the option to select which Multifactor Authentication Method you wish to use. Prior to v2.0, mfa_method is always required.

Option 1: TOTP

Set mfa_method to soft-token.

Obtain the seed for mfa_token as follows:

Navigate to the Intuit MFA settings (or in your Mint setings page, navigate Intuit Account -> Sign In & Security -> Two-step verification).
Token MFA is only allowed as a secondary option, so first enable one of the other options (text, email, voice).
Now you're ready to setup token MFA. Select the Authenticator app option, and navigate through the prompts. If you already have TOTP enabled on your account, you will first have to disable and delete the old TOTP token before setting up a new one.
When you get to the part where you see the QR code, copy the manual setup code that appears next to it. This is the token you pass to mfa_token in either the python api or from the command line. BE CAREFUL WHERE YOU STORE THIS, as anyone with it will be able to take over your Mint account.
Complete the setup process by providing a generated code from your authenticator app when requested.

Option 2: Email

In order for mintapi to automate the retrieval of the MFA code from your email, your email provider must provide IMAP access. If you use IMAP in conjunction with keyring, then you can store your IMAP password (imap-password) in keyring. To do so, simply omit imap-password and you will initially be prompted for the password associated with your IMAP account. Then, on subsequent uses of your IMAP account, you will not have to specify your password.

Chrome

mintapi automatically downloads the latest stable chromedriver. For long term, automated deployments, verify that the particular chrome and chromedrive binaries you have downloaded work together, and use the --use_chromedriver_on_path flag to prevent mintapi from auto updating the chromedriver binary Keep these binaries separate from your regular installation to avoid accidental breakage via auto-update.

Use your distribution's package manager to install chromium and chromedriver:

# Debian/Ubuntu
sudo apt install chromium-browser chromium-chromedriver
# RHL/Fedora
sudo dnf install chromium-browser chromium-chromedriver
# Arch/Manjaro
sudo pacman -S chromium-browser chromium-chromedriver

You can also manually download a chromedriver version of your choice. To use your custom chromedriver in mintapi, you can either add it to your Python working directory or add it to your PATH as described in the Seleninum driver documentation.

(To use a browser other than Chrome/Chromium, see the python section below.)

Examples

Cron

The following cron job runs mintapi, looking for the chromium executable in /usr/bin, every day at 07:00:

0 7 * * * PATH=/usr/bin:$PATH mintapi --use_chromedriver_on_path --headless john@example.com my_password

Note that the PATH is only affected for this job, and will not change the environment for any other process.

This page has instructions for setting a scheduled task in Windows with Powershell. Running just once is as easy as:

$ENV:PATH = "C:\Program Files\Google\Chrome;$ENV:PATH"
mintapi --headless john@example.com my_password

Docker Image

You can also use the docker image to help manage your environment so you don't have to worry about chrome or chromedriver versions. There are a few caveats:

Headless mode is recommended. GUI works but introduces the need to configure an X11 server which varies with setup. Google is your friend.
Almost always use the flag --use-chromedriver-on-path as the chrome and chromedriver built into the docker image already match and getting the latest will break the image.
If you want to persist credentials or your chrome session, you'll need to do some volume mounting.

To use the image:

docker run --rm --shm-size=2g ghcr.io/mintapi/mintapi mintapi john@example.com my_password --headless --use-chromedriver-on-path

AWS Lambda Environment

AWS Lambda may need a specific chrome driver with specific options. You can initialize Mint with your own pre-configured headless serverless chrome through a constructor:

driver = initialize_serverless_chrome_driver(...)
mint = mintapi.Mint(..., driver=driver)
...

Multi-Data Support

As of v2.0, mintapi supports returning multiple types of data in one call, such as: mintapi --accounts --budgets --transactions. When exporting multiple data types, you can either send it directly to stdout or you can export to a file via --filename. mintapi will create a file for each type of data, with a suffix based on the format. For example, if you run mintapi --accounts --transactions --filename=current --format=csv, then you will receive two files: current_account.csv and current_transaction.csv. The following table outlines the option selected and its corresponding suffix:

| Option | Suffix | | ----------- | ----------- | | accounts | account | | bills | bills | | budgets | budget | | transactions | transaction | | trends | trends | | categories | category | | investments | investment | | net-worth | net_worth | | credit-score | credit_score | | credit-report| credit_report|

Financial Data Trends

Mint supports providing some analysis of your financial data based on different types of "trends". Mint's requirements for accessing this data using mintapi is a bit more complex than the other endpoints.

| Parameter | Data Type | Description | | ---------------- | ------------------ | ----------- | | report_type | ReportView.Options | The type of report to generate. | | date_filter | DateFilter.Options | The date window to analyze your trends. | | start_date | Optional[str] | An optional beginning date (mm-dd-yy) to your trend analysis. | | end_date | Optional[str] | An optional ending date (mm-dd-yy) to your trend analysis. | | category_ids | List[str] | An optional list of category IDs to include in your trend analysis. | | tag_ids | List[str] | An optional list of tag IDs to include in your trend analysis. | | descriptions | List[str] | An optional list of descriptions to include in y

Mintapi

Install / Use

README