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:
- Create a development account and login.
- Create a new application in the Customer Account Data category. It’s easiest to follow the instructions in the help documentation.
- 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!
- 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&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'
User’s Guide¶
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
torequests-oauthlib
because it is maintained and causing less issues. Plus, requests is awesome ;) - Added
verify_ssl
keyword argument toAggcatClient
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