Quick Start

Ready to get your financial data? This quickstart is intended to get you setup to start using Intuit’s Customer Account Data API.

Before Using The API Client

You must take a few steps on Intuit’s website before using the API client:

  1. Create a development account and login.
  2. Create a new application in the Customer Account Data category. It’s easiest to follow the instructions in the help documentation.
  3. Create and upload self a generated x509 certificate to your application. It’s easiest to use openssl to generate the certificate. It’s best to name your key the same as your application name. Don’t lose these certificates!
  4. Gather the login details and store them somewhere. You will need OAuth Consumer Key, Oauth Consumer Secret, SAML Identity Provider ID

Installation

pip install python-aggcat

Known Issues

The SSL library in Python 2.6 and below has a bug and will not parse the AlternativeNames out of the Intuit SSL cert causing a name mismatch during cetificate validation. For now, please pass verify_ssl = False to the AggcatClient when initializing it. While less secure, I wanted the verification to be turned off explictly so you are aware. If possible, upgrade to Python 2.7+.

Initializing the API Client

Assuming you have an OAuth Consumer Key, Oauth Consumer Secret, SAML Identity Provider ID, and a path to the x509 certificates you generated you are ready to start querying:

from aggcat import AggcatClient

client = AggcatClient(
    'oauth_consumer_key',
    'oauth_consumer_secret',
    'saml_identity_provider_id',
    'customer_id',
    '/path/to/x509/appname.key'
)

Note

customer_id (Integer) It can be any integer. You should try using the database primary key of a user in your system or some other unique identifier such as a guid. If you are just testing you can use whatever integer you want.

objectify (Boolean) This is a BETA functionality. It will objectify the XML returned from intuit into standard python objects so you don’t have to mess with XML. Default: True

Querying the API

Here are a few sample queries that don’t require you to add an account

Getting all institutions

institutions = client.get_institutions()

Note

This query will take a very long time depending on your internet connection. It returns 18000+ institutions in XML format. Sux :(

If you are using the objectify = True keyword argument on the client you can access the institutions in a pythonic way

>>> institutions = client.get_institutions()
>>> len(institutions.content)
18716
>>> institutions.content[0].institution_name
'Carolina Foothills FCU Credit Card'

Searching for your institution

Currently finding an institution is somewhat of a manual process. Soon, there will be a helper method on the client that will have a better search. Patches welcome ;). This example searches for an institution that contains “chase” in any of the XML elements:

from aggcat import AggcatClient
from lxml import etree
from aggcat.utils import remove_namespaces

client = AggcatClient(
    'oauth_consumer_key',
    'oauth_consumer_secret',
    'saml_identity_provider_id',
    'customer_id',
    '/path/to/x509/appname.key'
)

search_string = 'Chase'
institutions = client.get_institutions()

xml = etree.fromstring(institutions.content.to_xml())
xml = etree.fromstring(remove_namespaces(xml))

for element in xml.xpath('./institution[contains(., "chase")]'):
    id = element.xpath('./institutionId')[0].text
    name = element.xpath('./institutionName')[0].text
    print id, name
13278 JP Morgan Chase Bank
13640 Quicken Visa
14554 Chase Bank Credit Card (Amazon.com)
14910 Chase e-Funds Card
14777 Fox Chase Bank - Business Banking
13718 Fox Chase Bank
14484 Chevy Chase Bank - Web Cash Manager
...

Note

This query will take a very long time depending on your internet connection. It returns 18000+ institutions in XML format. Sux :(

Getting the institution details

From the previous search example, we can use 13728 to get the institution details

institution_details = client.get_institution_details(13278)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><InstitutionDetail xmlns="http://schema.intuit.com/platform/fdatafeed/institution/v1" xmlns:ns2="http://schema.intuit.com/platform/fdatafeed/common/v1"><institutionId>13278</institutionId><institutionName>JP Morgan Chase Bank</institutionName><homeUrl>https://www.chase.com/</homeUrl><phoneNumber>1-877-242-7372</phoneNumber><address><ns2:address1>P O Box 36520</ns2:address1><ns2:address2>Suite IL1-0291</ns2:address2><ns2:city>Louisville</ns2:city><ns2:state>KY</ns2:state><ns2:postalCode>40233</ns2:postalCode><ns2:country>USA</ns2:country></address><emailAddress>http://www.chase.com/cm/cs?pagename=Chase/Href&amp;urlname=chase/cc/contactus/email</emailAddress><specialText>Please enter your JP Morgan Chase Bank User ID and Password required for login.</specialText><currencyCode>USD</currencyCode><keys><key><name>usr_password</name><status>Active</status><displayFlag>true</displayFlag><displayOrder>2</displayOrder><mask>true</mask><description>Password</description></key><key><name>usr_name</name><status>Active</status><displayFlag>true</displayFlag><displayOrder>1</displayOrder><mask>false</mask><description>User ID</description></key></keys></InstitutionDetail>

If you are using the objectify = True keyword argument on the client you can access the institution parameters in a Pythonic way

>>> institution = client.get_institution_details(13278)
>>> institution
<AggCatResponse 200>
>>> institution.content
<Institutiondetail object @ 0x10ddfa4d0>
>>> institution.content.institution_name
'JP Morgan Chase Bank'
>>> institution.content.home_url
'https://www.chase.com/'
>>> institution.currency_code
'USD'

Release Notes

0.9

  • Fixed the challenge update method

0.8

  • Added missing query parameters to post and put update so refreshes work correctly.
  • Updated tests

0.7

  • Fixed an issue where responses that came back empty would return None instead of an AggcatResponse object

0.6

  • Fixed a missing comma in helpers
  • Added headers to the AggCat Response object

0.5

  • Updated helpers to use uppercase values in the XML when updating account type

0.4

  • Updates to the docs

0.3

  • Switched oAuth backend from oAuth2 to requests-oauthlib because it is maintained and causing less issues. Plus, requests is awesome ;)
  • Added verify_ssl keyword argument to AggcatClient so that the library work under Python 2.6 due to an SSL library bug parsing Intuits SSL Certificate. See Known Issues
  • Added Counter backport for Python 2.6 http://code.activestate.com/recipes/576611-counter-class/

0.2

  • Cleanup
  • Made end_date an optional parameter in get_account_transactions to reflect intuit
  • Added requirements.pip file do that docs build correctly on readthedocs.org

0.1

  • Initial Release