The official python client library for the Plaid API, which is generated from our OpenAPI spec. For the last non-generated version of our library, go here.
This library only supports python3!
$ pip3 install plaid-pythonThe module supports all Plaid API endpoints. For complete information about the API, head to the docs.
To call an endpoint you must create a PlaidApi object.
import plaid
from plaid.api import plaid_api
# Available environments are
# 'Production'
# 'Development'
# 'Sandbox'
configuration = plaid.Configuration(
host=plaid.Environment.Sandbox,
api_key={
'clientId': client_id,
'secret': secret,
}
)
api_client = plaid.ApiClient(configuration)
client = plaid_api.PlaidApi(api_client)Each endpoint returns a dictionary which contains the parsed JSON from the HTTP response.
This release only supports the latest Plaid API version, 2020-09-14.
For information about what has changed between versions and how to update your integration, head to the API upgrade guide.
The plaid-python client library is typically updated on a biweekly basis. The canonical source for the latest version number is the client library changelog.
All non-200 responses will throw a plaid.ApiException.
import plaid
from plaid.model.asset_report_get_request import AssetReportGetRequest
try:
request = AssetReportGetRequest(
asset_report_token=asset_report_token,
)
return client.asset_report_get(request)
except plaid.ApiException as e:
response = json.loads(e.body)
# check the code attribute of the error to determine the specific error
if response['error_code'] == 'ITEM_LOGIN_REQUIRED':
# the users' login information has changed, generate a public_token
# for the user and initialize Link in update mode to
# restore access to this user's data
# see https://plaid.com/docs/api/#updating-items-via-link
else:
...For more information on Plaid response codes, head to the docs.
As this is a common question, we've included this in the README. plaid-python uses models like TransactionsGetResponse to encapsulate API responses. If you want to convert this to a JSON, do something like this:
import json
...
response = ... # type TransactionsGetResponse
# to_dict makes it first a python dictionary, and then we turn it into a string JSON.
json_string = json.dumps(response.to_dict())Dates and date times in requests and responses, which are represented as strings in the API and in previous client library versions, are represented in this version of the library as Python datetime.date or datetime.datetime objects. If you need to convert between dates and strings, you can use the datetime.strptime method. For an example, see the Retrieve Transactions sample code later in this Readme.
While the API and previous library versions represent enums using strings, this current library uses Python classes with restricted values.
Old:
'products': ['auth', 'transactions'],
'country_codes': ['US'],
Current:
products=[Products('auth'), Products('transactions')],
country_codes=[CountryCode('US')],
Exchange a public_token from Plaid Link for a Plaid access token:
import plaid
from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest
# the public token is received from Plaid Link
exchange_request = ItemPublicTokenExchangeRequest(
public_token=pt_response['public_token']
)
exchange_response = client.item_public_token_exchange(exchange_request)
access_token = exchange_response['access_token']Exchange a Plaid Link public_token for an API access_token. Then exchange
that access_token and the Plaid Link account_id (received along with the
public_token) for a Stripe bank_account_token:
import plaid
from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest
from plaid.model.processor_stripe_bank_account_token_create_request import ProcessorStripeBankAccountTokenCreateRequest
exchange_request = ItemPublicTokenExchangeRequest(
public_token=pt_response['public_token']
)
exchange_response = client.item_public_token_exchange(exchange_request)
access_token = exchange_response['access_token']
request = ProcessorStripeBankAccountTokenCreateRequest(
access_token=access_token,
account_id='[Account ID]',
)
stripe_response = client.processor_stripe_bank_account_token_create(request)
bank_account_token = stripe_response['stripe_bank_account_token']import plaid
from plaid.model.item_remove_request import ItemRemoveRequest
# Provide the access token for the Item you want to remove
request = ItemRemoveRequest(
access_token=accessToken
)
response = client.item_remove(request)import plaid
from plaid.model.transactions_get_request_options import TransactionsGetRequestOptions
from plaid.model.transactions_get_request import TransactionsGetRequest
request = TransactionsGetRequest(
access_token=access_token,
start_date=datetime.strptime('2020-01-01', '%Y-%m-%d').date(),
end_date=datetime.strptime('2021-01-01', '%Y-%m-%d').date(),
)
response = client.transactions_get(request)
transactions = response['transactions']
# the transactions in the response are paginated, so make multiple calls while increasing the offset to
# retrieve all transactions
while len(transactions) < response['total_transactions']:
options = TransactionsGetRequestOptions()
options.offset = len(transactions)
request = TransactionsGetRequest(
access_token=access_token,
start_date=datetime.strptime('2020-01-01', '%Y-%m-%d').date(),
end_date=datetime.strptime('2021-01-01', '%Y-%m-%d').date(),
options=options
)
response = client.transactions_get(request)from plaid.model.asset_report_pdf_get_request import AssetReportPDFGetRequest
pdf_request = AssetReportPDFGetRequest(asset_report_token=PDF_TOKEN)
pdf = client.asset_report_pdf_get(pdf_request)
FILE = open('asset_report.pdf', 'wb')
FILE.write(pdf.read())
FILE.close()Public endpoints (category information) require no authentication and can be accessed as follows:
categories = client.categories_get({})Authenticated endpoints require a (client_id, secret) pair. You do not need to pass in authentication to individual endpoints once you have set it on the plaid.Configuration object.
Please see Contributing for guidelines and instructions for local development.