Package: mintapi
mintapiAn unofficial screen-scraping API for Mint.com.mintapiscrapes Mint.com by using Selenium/WebDriver to navigate a browser.
Once logged in,mintapiallows programatic, automated access to Mint's UI.IMPORTANT: mintapi 2.0 vs 1.x and breaking changesWe recently released 2.0, which supports (and only supports) the new Mint UI:If your account has the new UI with the nav on theleft, you'll need to install at least 2.0:pip install mintapi>=2.0If your account still has the original UI with the nav ontop, to use 2.0, you will need to specify--betain your command-line options or submitbeta=Truewhen initializing the class.  Otherwise, please install the latest 1.x release:pip install mintapi<2.0Please notethat 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 seethe CHANGELOGfor details.InstallationInstall with pip from PyPipipinstallmintapiOr for the latest release:pipinstallgit+https://github.com/mintapi/mintapiThen simply:mintapi--keyring--headlessyou@example.comYou 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.mintapipersists 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-fileargument.
For arguments such as--transactions,
you can add a line in your config file that saystransactions.
For other arguments that have input,
such as--start-date,
you would add a line such asstart-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, pleasejoin us on Discord! :)Complete SetupMFA Authentication MethodsMint accepts MFA in one of four ways: text, voice, email, or TOTP
(Time-basedOne-TimePassword).mintapisupports 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 sometimesstill 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_methodis always required.Option 1: TOTPSetmfa_methodtosoft-token.Obtain the seed formfa_tokenas follows:Navigate to theIntuit MFA settings(or in your Mint setings page, navigateIntuit 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 theAuthenticator appoption, 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 themanual setup codethat appears next to it.
This is the token you pass tomfa_tokenin 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: EmailIn order formintapito automate the retrieval of the MFA code from your email,
your email provider must provide IMAP access. If you use IMAP in conjunction withkeyring,
then you can store your IMAP password (imap-password) in keyring. To do so,
simply omitimap-passwordand 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.Chromemintapiautomatically 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_pathflag to preventmintapifrom 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/Ubuntusudoaptinstallchromium-browserchromium-chromedriver# RHL/Fedorasudodnfinstallchromium-browserchromium-chromedriver# Arch/Manjarosudopacman-Schromium-browserchromium-chromedriverYou can alsomanually download a chromedriverversion of your choice.
To use your custom chromedriver inmintapi,
you can either add it to your Python working directory
or add it to yourPATHas described in theSeleninum driver documentation.(To use a browser other than Chrome/Chromium,
see thepython sectionbelow.)ExamplesCronThe following cron job runsmintapi,
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_passwordNote that thePATHis only affected for this job,
and will not change the environment for any other process.This pagehas 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--headlessjohn@example.commy_passwordDocker ImageYou 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-pathas 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-pathAWS Lambda EnvironmentAWS Lambda may need aspecific 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 SupportAs 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 tostdoutor 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 runmintapi --accounts --transactions --filename=current --format=csv, then you will receive two files:current_account.csvandcurrent_transaction.csv.  The following table outlines the option selected and its corresponding suffix:OptionSuffixaccountsaccountbillsbillsbudgetsbudgettransactionstransactiontrendstrendscategoriescategoryinvestmentsinvestmentnet-worthnet_worthcredit-scorecredit_scorecredit-reportcredit_reportFinancial Data TrendsMint 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.ParameterData TypeDescriptionreport_typeReportView.OptionsThe type of report to generate.date_filterDateFilter.OptionsThe date window to analyze your trends.start_dateOptional[str]An optional beginning date (mm-dd-yy) to your trend analysis.end_dateOptional[str]An optional ending date (mm-dd-yy) to your trend analysis.category_idsList[str]An optional list of category IDs to include in your trend analysis.tag_idsList[str]An optional list of tag IDs to include in your trend analysis.descriptionsList[str]An optional list of descriptions to include in your trend analysis.account_idsList[str]An optional list of account IDs to include in your trend analysis.match_all_filtersbooleanWhether to match all supplied filters (True) or at least one (False)limitintThe page size of results.offsetintThe starting record of your results.Report TypeThe Report Type is the type of report for which to generate trend analysis.  The supplied value must be one of the following enum values:Enum ValueDescription1Spending Over Time2Spending by Category3Spending by Merchant4Spending by Tag5Income Over Time6Income by Category7Income by Merchant8Income by Tag9Assets by Type10Assets Over Time11Assets by Account12Debts Over Time13Debts by Type14Debts by Account15Net Worth Over Time16Net Income Over TimeFinancial Data TransactionsIf you want to provide a more granular filtering of your financial data transactions, you can select from a variety of search filters that are sent to Mint.ParameterData TypeDescriptiondate_filterDateFilter.OptionsThe date window for which to filter your transactions.start_dateOptional[str]An optional beginning date (mm-dd-yy) to your transaction filtering.end_dateOptional[str]An optional ending date (mm-dd-yy) to your transaction filtering.category_idsList[str]An optional list of category IDs of transactions to include.tag_idsList[str]An optional list of tag IDs of transactions to include.descriptionsList[str]An optional list of descriptions of transactions to include.account_idsList[str]An optional list of account IDs of transactions to include.match_all_filtersbooleanWhether to match all supplied filters (True) or at least one (False)include_investmentbooleanWhether to include those transactions that are associated with an Investment Account.remove_pendingbooleanWhether to remove those transactions that are still Pending.limitintThe page size of results.offsetintThe starting record of your results.Date FiltersThe Date Filter is the date window for which to generate your trend analysis or for which to search transactions.  The supplied value must be one of the following enum values:Enum ValueDescription1Last 7 Days2Last 14 Days3This Month4Last Month5Last 3 Months6Last 6 Months7Last 7 Months8This Year9Last Year10All Time11CustomIf you select a Custom Date Filter, thenstart_dateandend_dateare required fields.  Similarly, if you wish to usestart_dateandend_date, Custom Date Filter must be used.From PythonFrom python, instantiate the Mint class (from the mintapi package) and you can
make calls to retrieve account/budget information.  We recommend using thekeyringlibrary for persisting credentials.importmintapimint=mintapi.Mint('your_email@web.com',# Email used to log in to Mint'password',# Your password used to log in to mint# Optional parametersmfa_method='sms',# See MFA Methods section# Can be 'sms' (default), 'email', or 'soft-token'.# if mintapi detects an MFA request, it will trigger the requested method# and prompt on the command line.mfa_input_callback=None,# see MFA Methods section# can be used with any mfa_method# A callback accepting a single argument (the prompt)# which returns the user-inputted 2FA code. By default# the default Python `input` function is used.mfa_token=None,# see MFA Methods section# used with mfa_method='soft-token'# the token that is used to generate the totpintuit_account=None,# account name when multiple accounts are registered with this email.headless=False,# Whether the chromedriver should work without opening a# visible window (useful for server-side deployments)# None will use the default account.session_path=None,# Directory that the Chrome persistent session will be written/read from.# To avoid the 2FA code being asked for multiple times, you can either set# this parameter or log in by hand in Chrome under the same user this runs# as.imap_account=None,# account name used to log in to your IMAP serverimap_password=None,# account password used to log in to your IMAP serverimap_server=None,# IMAP server host nameimap_folder='INBOX',# IMAP folder that receives MFA emailwait_for_sync=False,# do not wait for accounts to syncwait_for_sync_timeout=300,# number of seconds to wait for syncfail_if_stale=True,# True will raise an exception if Mint is unable to refresh your data.use_chromedriver_on_path=False,# True will use a system provided chromedriver binary that# is on the PATH (instead of downloading the latest version)driver=None,# pre-configured driver. If None, Mint will initialize the WebDriver.quit_driver_on_fail=True# Quit from the browser and driver if an unexpected exception caught.# Could be useful to set it to False if the ownership of the driver should not be owned by Mint object.)# Get account informationmint.get_account_data()# Get budget informationmint.get_budget_data()# Get transactionsmint.get_transaction_data()# as pandas dataframe# Get transactions for a specific accountaccounts=mint.get_account_data()foraccountinaccounts:mint.get_transaction_data(id=account["id"])# Get net worthmint.get_net_worth_data()# Get credit scoremint.get_credit_score_data()# Get billsmint.get_bills()# Get investments (holdings and transactions)mint.get_investment_data()# Get tagsmint.get_tag_data()# Get rules for assigning category and descriptionmint.get_rule_data()# Close session and exit cleanly from selenium/chromedrivermint.close()# Initiate an account refreshmint.initiate_account_refresh()# you can also use mintapi's login in workflow with your own selenium webdriver# this will allow for more custom selenium driver setups# one caveat is that it must be based on seleniumrequests currently# seleniumrequests has most browsers already# it also has mixins for any browsers it doesn't have so the sky is the limit!fromseleniumrequestsimportFirefoxmint=mintapi.Mint()mint.driver=Firefox()mint.status_message,mint.token=mintapi.sign_in(email,password,mint.driver,mfa_method=None,mfa_token=None,mfa_input_callback=None,intuit_account=None,wait_for_sync=True,wait_for_sync_timeout=5*60,imap_account=None,imap_password=None,imap_server=None,imap_folder="INBOX",)# now you can do all the normal api calls# ex:mint.get_transaction_data()Run it as a sub-process from your favorite language;pip install mintapicreates a binary in your $PATH. From the command-line, the output is JSON:usage:mintapi[-h][--session-path[SESSION_PATH]][--accounts][--investments][--beta][--budgets|--budget_hist][--net-worth][--credit-score][--credit-report][--exclude-inquiries][--exclude-accounts][--exclude-utilization][--start-date[START_DATE]][--end-date[END_DATE]][--limit][--include-investment][--show-pending][--format][--filenameFILENAME][--keyring][--headless][--mfa-method{sms,email,soft-token}][--categories][--attention][--transactions][--transaction-date-filter][--trends][--trend-report-type][--trend-date-filter]email[password]positionalarguments:emailThee-mailaddressforyourMint.comaccount(required)passwordThepasswordforyourMint.comaccount(ifnotsupplied,--keyringmustbeprovided)optionalarguments:-h,--helpshowthishelpmessageandexit--accountsRetrieveaccountinformation(defaultifnothingelseisspecified)--session-path[SESSION_PATH]Directorytosavebrowsersession,includingcookies.UsedtopreventrepeatedMFAprompts.Defaultsto$HOME/.mintapi/session.SettoNonetouseatemporaryprofile.--betaUsethebetaversionofMint--billsRetrievebillsinformation--budgetsRetrievebudgetinformationforcurrentmonth--budget_histRetrievehistoricalbudgetinformation(past12months)--categoriesRetrieveyourconfiguredMintcategories--config-file,-cFileusedtostorearguments--credit-scoreRetrievecreditscore--credit-reportRetrievefullcreditreport&history--exclude-inquiriesUsedinconjunctionwith--credit-report,ignorescreditinquirydata.--exclude-accountsUsedinconjunctionwith--credit-report,ignorescreditaccountdata.--exclude-utilizationUsedinconjunctionwith--credit-report,ignorescreditutilizationdata.--net-worthRetrievenetworthinformation--transactions,-tRetrievetransactions--transaction-date-filterThedatewindowforwhichtofilteryourtransactions.DefaultisAllTime.--trendsRetrievetrenddatarelatedtoyourfinancialinformation--trend-report-typeThetypeofreportforwhichtogeneratetrendanalysis.DefaultisSpendingOverTime.--trend-date-filterThedatewindowforwhichtogenerateyourtrendanalysis.DefaultisThisMonth.--start-date[START_DATE]Earliestdateforwhichtoretrievetransactions.Usedwith--transactions.Format:mm/dd/yy--end-date[END_DATE]Latestdateforwhichtoretrievetransactions.Usedwith--transactions.Format:mm/dd/yy--investmentsRetrievedatarelatedtoyourinvestments,whethertheyberetirementorpersonalstockpurchases--include-investmentUsedwith--transactions--limitNumberofrecordstoincludefromtheAPI.Defaultis5000.--show-pendingRetrievependingtransactions.Usedwith--transactions--fail-if-staleAtlogin,Mintattemptstorefreshyourdata.Ifyouwishtoexitwhenthesyncfails,usethisoption.--filenameFILENAME,-fFILENAMEwriteresultstofile.Ifnofileisspecified,thendataiswrittentostdout.Donotspecifythefileextensionasitisdeterminedbasedontheselectionof`--format`.--formatDeterminestheoutputformatofthedata,either`csv`or`json`.Thedefaultvalueis`json`.Ifno`filename`isspecified,thenthisdeterminesthe`stdout`format.Otherwise,ifa`filename`isspecified,thenthisdeterminesthefileextension.--keyringUseOSkeyringforstoringpasswordinformation--headlessWhethertoexecutechromedriverwithnovisiblewindow.--use-chromedriver-on-pathWhethertousethechromedriveronPATH,insteadofdownloadingalocalcopy.--mfa-method{sms,email,soft-token}TheMFAmethodtoautomate.--mfa-tokenThebase32encodedMFAtoken.--imap-accountIMAP_ACCOUNT--imap-passwordIMAP_PASSWORD--imap-serverIMAP_SERVER_HOSTNAME--imap-folderIMAP_FOLDERDefaultisINBOX--imap-testTestaccesstoIMAPserver--no_wait_for_syncDonotwaitforaccountstosync--wait_for_sync_timeoutNumberofsecondstowaitforsync(defaultis300)--attention.Getnoticeifthereareanyaccountsthatneedattention>>>mintapi--keyringemail@example.com[{"accountName":"Chase Checking","lastUpdatedInString":"25 minutes","accountType":"bank","currentBalance":100.12,...},...]Special ConsiderationsEmail / Account AccessBecause of the inter-connected nature of Intuit's products, when signing in to Mint for one account, you may see accounts associated with Intuit products other than Mint.  If you do have multiple Intuit accounts, you should be aware that if one email is associated with two different usernames (and multiple Intuit products, such as TurboTax or Quickbooks), you may receive a prompt for Multifactor Authentication, even with a saved session.  One possible solution is separating the two accounts to use two different emails.  For many email clients, you can route different email addresses to the same account by using a suffix.  For example, you could have email addresses "myaccount+mint@gmail.com" and "myaccount+quickbooks@gmail.com" and receive emails for both in the "myaccount@gmail.com" inbox.Chrome versionNOTE: You must haveChromeorChromiuminstalled, on thestabletrack, and be up-to-date!If you run into aSessionNotCreatedExceptionabout "ChromeDriver only supports Chrome version XX",
you need toupdate Chrome.