Plaid Python Documentation!

Client

class plaid.Client(client_id=None, secret=None, environment=None, suppress_warnings=False, timeout=600, api_version=None, client_app=None)

Python Plaid API client.

See official documentation at: https://plaid.com/docs.

All of the endpoints documented under the plaid.api module may be called from a plaid.Client instance.

__init__(client_id=None, secret=None, environment=None, suppress_warnings=False, timeout=600, api_version=None, client_app=None)

Initialize a client with credentials.

Parameters

  • client_id (str) – Your Plaid client ID

  • secret (str) – Your Plaid secret

  • environment (str) – One of sandbox, development, or production.

  • suppress_warnings (bool) – Suppress Plaid warnings.

  • timeout (int) – Timeout for API requests.

  • api_version (str) – API version to use for requests

  • client_app (str) – Internal header to include in requests

API Endpoints

Many API endpoints accept optional parameters via an _options object in the raw JSON. To improve forward compatibility as options are added, the Python functions for these endpoints also include an _options argument. However, it is recommended that you pass in options using the provided keyword arguments where possible.

For example:

// Prefer this...
client.Transactions.get(access_token,
                        start_date,
                        end_date,
                        account_ids=account_ids,
                        count=count,
                        offset=offset);

// ... over this.
client.Transactions.get(access_token,
                        start_date,
                        end_date,
                        _options={
                          'account_ids': account_ids,
                          'count': count,
                          'offset': offset,
                        });
class plaid.api.Accounts(client)

Accounts endpoints. (HTTP docs)

class Balance(client)

Accounts balance endpoint.

Balance.get(access_token, _options=None, account_ids=None)

Retrieve real-time balance information for accounts.

Parameters

  • access_token (str) –

  • account_ids ([str]) – A list of account_ids to retrieve for the item. Optional.

get(access_token, _options=None, account_ids=None)

Retrieve high-level account information for an Item.

Parameters

  • access_token (str) –

  • account_ids ([str]) – A list of account_ids to retrieve for the item. Optional.

class plaid.api.AssetReport(client)

Assets endpoints. (HTTP docs)

create(access_tokens, days_requested, options=None)

Create an asset report.

Parameters

  • access_tokens ([str]) – A list of access tokens, one token for each Item to be included in the Asset Report.

  • days_requested (int) – Days of transaction history requested to be included in the Asset Report.

  • options (dict) – An optional dictionary. For more information on the options object, see the documentation site listed above.

filter(asset_report_token, account_ids_to_exclude)

Create a new, filtered asset report based on an existing asset report.

Parameters

  • asset_report_token (str) – The existing Asset Report’s asset report token.

  • account_ids_to_exclude ([str]) – A list of account IDs to exclude from the new Asset Report.

get(asset_report_token, include_insights=False)

Retrieves an asset report.

Parameters

  • asset_report_token (str) – The asset report token for the asset report you created.

  • include_insights (bool) – An optional boolean specifying whether we should retrieve the report as an Asset Report with Insights. For more, see https://plaid.com/docs/#retrieve-json-report-request.

get_pdf(asset_report_token)

Retrieves an asset report in the PDF format.

Parameters

asset_report_token (str) – The asset report token for the asset report you created.

refresh(asset_report_token, days_requested, options=None)

Create a new, refreshed asset report based on an existing asset report.

Parameters

  • asset_report_token (str) – The existing Asset Report’s asset report token.

  • days_requested (int) – Days of transaction history requested to be included in the Asset Report.

  • options (dict) – An optional dictionary. This is the same object used in create.

remove(asset_report_token)

Retrieves an asset report in the PDF format.

Parameters

asset_report_token (str) – The asset report token for the asset report you want to remove.

class plaid.api.Auth(client)

Auth endpoints.

get(access_token, _options=None, account_ids=None)

Retrieve account and routing numbers for checking and savings accounts. (HTTP docs)

Parameters

  • access_token (str) –

  • account_ids ([str]) – A list of account_ids to retrieve for the item. Optional.

class plaid.api.Categories(client)

Categories endpoints. (HTTP docs)

get()

Fetch all plaid categories.

class plaid.api.CreditDetails(client)

Credit details endpoints. (HTTP docs)

get(access_token)

Retrieve credit details associated with an item.

Parameters

access_token (str) –

class plaid.api.DepositSwitch(client)

Deposit Switch endpoints. (HTTP docs)

create(target_account_id, target_access_token)

Creates a deposit switch given target account id and target access token. (HTTP docs)

Parameters

  • target_account_id (str) – The id of the bank account that the deposit switch will go to.

  • target_access_token (str) – The access token to create the the deposit switch.

create_token(deposit_switch_id)

Creates a deposit switch token, which is used to initialize a deposit switch. (HTTP docs)

Parameters

deposit_switch_id (str) – ID of deposit switch

get(deposit_switch_id)

Gets deposit switch information given a deposit switch id.

Parameters

deposit_switch_id (str) – ID of deposit switch to get.

class plaid.api.Holdings(client)

Holdings endpoints. (HTTP docs)

get(access_token, _options=None, account_ids=None)

Retrieve investment holdings information about an item.

Parameters

  • access_token (str) –

  • account_ids ([str]) – A list of account_ids to retrieve for the item. Optional.

class plaid.api.Identity(client)

Identity endpoints. (HTTP docs)

get(access_token)

Retrieve information about an item.

Parameters

access_token (str) –

class plaid.api.Income(client)

Income endpoints. (HTTP docs)

get(access_token)

Retrieve income data associated with an item. Adds the income product to the item if it does not already have it.

Parameters

access_token (str) –

class plaid.api.Institutions(client)

Institutions endpoints. (HTTP docs)

get(country_codes, count, offset=0, _options=None)

Fetch all Plaid institutions, using /institutions/all.

Parameters

  • country_codes ([str]) – Country codes of institutions to fetch.

  • count (int) – Number of institutions to fetch.

  • offset (int) – Number of institutions to skip.

get_by_id(institution_id, country_codes, _options=None)

Fetch a single institution by id.

Parameters

  • country_codes ([str]) – Country codes of institution to fetch.

  • institution_id (str) –

search(query, country_codes, _options=None, products=None)

Search all institutions by name.

Parameters

  • country_codes ([str]) – Country codes of institutions to fetch.

  • query (str) – Query against the full list of institutions.

  • products ([str]) – Filter FIs by available products. Optional.

class plaid.api.InvestmentTransactions(client)

InvestmentTransactions endpoints.

get(access_token, start_date, end_date, _options=None, account_ids=None, count=None, offset=None)

Return accounts and investment transactions for an item. (HTTP docs)

The transactions in the response are paginated – compare the number of transactions received so far against response[‘total_transactions’] to determine whether to fetch another page.

Parameters

  • access_token (str) –

  • start_date (str) – The earliest date for transactions.

  • end_date (str) – The latest date for transactions.

  • account_ids ([str]) – A list of account_ids to retrieve for the item. Optional.

  • count (int) – The number of transactions to fetch. Optional.

  • offset (int) – The number of transactions to skip from the beginning of the fetch. Optional.

All date should be formatted as YYYY-MM-DD.

class plaid.api.Item(client)

Item endpoints. (HTTP docs)

class AccessToken(client)

Access token endpoints.

AccessToken.invalidate(access_token)

Rotate the access token for an item. (HTTP docs)

Parameters

access_token (str) –

class PublicToken(client)

Endpoints for translating between public tokens and access tokens.

PublicToken.create(access_token)

Create a Link public_token for an API access_token. (HTTP docs) :param str access_token:

PublicToken.exchange(public_token)

Exchange a Link public_token for an API access_token. (HTTP docs)

Parameters

public_token (str) –

class Webhook(client)

Webhook endpoints.

Webhook.update(access_token, webhook)

Update the webhook for an Item. (HTTP docs)

Parameters

  • access_token (str) –

  • webhook (str) – The URL of the webhook to associate.

get(access_token)

Get information about the status of an item. (HTTP docs)

Parameters

access_token (str) –

import_item(products, user_auth, _options)

Imports an item. (`HTTP docs coming soon`__)

Parameters

  • initial_products ([str]) – List of products that the item will be enabled for.

  • user_auth (dict) – User authentication fields for the item.

  • options (dict) – Additional options.

remove(access_token)

Remove an item. (HTTP docs)

This also deactivates the access_token.

Parameters

access_token (str) –

class plaid.api.Liabilities(client)

Liabilities endpoints. (HTTP docs)

get(access_token, _options=None, account_ids=None)

Retrieve liabilities information about an item.

Parameters

  • access_token (str) –

  • account_ids ([str]) – A list of account_ids to retrieve for the item. Optional

class plaid.api.LinkToken(client)

Endpoints for managing link tokens.

create(configs)

Create a Link token.

Parameters

configs (dict) – A required dictionary to configure the Link token.

get(link_token)

Get information about a Link token.

Parameters

link_token (string) – A valid link token created from

link/token/create.

class plaid.api.PaymentInitiation(client)

Payment Initiation endpoints.

create_payment(recipient_id, reference, amount)

Creates a payment.

Parameters

  • recipient_id (str) –

  • reference (str) –

  • amount (dict) – A dictionary containing currency and value fields.

create_payment_token(payment_id)

Creates a payment. :param str payment_id:

create_recipient(name, iban, address, bacs)

Creates a payment recipient.

Parameters

  • name (str) –

  • iban (str) –

  • address (dict) – A dictionary containing street, city, postal_code, and country fields.

  • bacs (dict) – A dictionary containing account and sort_code

get_payment(payment_id)

Retrieves a payment.

Parameters

payment_id (str) –

get_recipient(recipient_id)

Retrieves a payment recipient.

Parameters

recipient_id (str) –

list_payments(options)

Lists all the payments.

Parameters

options (dict) – A dictionary containing count, and cursor fields.

list_recipients()

Lists all the payment recipients.

class plaid.api.Processor(client)

Endpoints for creating processor tokens.

dwollaBankAccountTokenCreate(access_token, account_id)

Create a Dwolla processor token for a given account ID (HTTP docs)

Parameters

  • access_token (str) –

  • account_id (str) –

stripeBankAccountTokenCreate(access_token, account_id)

Create a Stripe bank_account token for a given account ID (HTTP docs)

Parameters

  • access_token (str) –

  • account_id (str) –

tokenCreate(access_token, account_id, processor)

Create a processor token for a given processor and account ID

Parameters

  • access_token (str) –

  • account_id (str) –

  • processor (str) –

class plaid.api.Sandbox(client)

Sandbox-only endpoints. (HTTP docs)

These endpoints may not be used in other environments.

class Item(client)

Sandbox item endpoints.

Item.fire_webhook(access_token, webhook_code)

Fire a webhook for an item

Parameters

  • access_token (str) –

  • webhook_code (str) –

Item.reset_login(access_token)

Put an item into an ITEM_LOGIN_REQUIRED error state.

Parameters

access_token (str) –

Item.set_verification_status(access_token, account_id, verification_status)

Set verification status for an item created via the automated microdeposits flow

Parameters

  • access_token (str) –

  • account_id (str) –

  • verification_status (str) –

class plaid.api.Transactions(client)

Transactions endpoints.

get(access_token, start_date, end_date, _options=None, account_ids=None, count=None, offset=None)

Return accounts and transactions for an item. (HTTP docs)

The transactions in the response are paginated – compare the number of transactions received so far against response[‘total_transactions’] to determine whether to fetch another page.

Parameters

  • access_token (str) –

  • start_date (str) – The earliest date for transactions.

  • end_date (str) – The latest date for transactions.

  • account_ids ([str]) – A list of account_ids to retrieve for the item. Optional.

  • count (int) – The number of transactions to fetch. Optional.

  • offset (int) – The number of transactions to skip from the beginning of the fetch. Optional.

All date should be formatted as YYYY-MM-DD.

refresh(access_token)

Request on-demand refresh of transactions and balances for an Item (HTTP docs)

Calls to /transactions/refresh will initiate an on-demand check for new transactions since last scheduled update. If there are fresh transactions, Plaid will fire a webhook. To fetch these transactions, call /transactions/get.

Parameters

access_token (str) –

class plaid.api.Webhooks(client)

Webhooks endpoints. (HTTP docs)

get_verification_key(key_id)

Retrieve webhook verification key.

Parameters

key_id (str) – ID of key from Plaid-Verification header

Errors

exception plaid.errors.BaseError(message, type, code, display_message)

Bases: Exception

A base error class.

Variables

  • message (str) – A developer-friendly error message. Not safe for programmatic use.

  • type (str) – A broad categorization of the error, corresponding to the error class.

  • code (str) – An error code for programmatic use.

  • display_message (str) – A user-friendly error message. Not safe for programmatic use. May be None.

exception plaid.errors.PlaidError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.BaseError

A Plaid API error.

Variables

  • message (str) – A developer-friendly error message. Not safe for programmatic use.

  • type (str) – A broad categorization of the error, corresponding to the error class.

  • code (str) – An error code for programmatic use.

  • display_message (str) – A user-friendly error message. Not safe for programmatic use. May be None.

  • request_id (str) – A unique id returned for all server responses.

  • causes (list) – A list of reasons explaining why the error happened.

static from_response(response)

Create an error of the right class from an API response.

:param response dict Response JSON

exception plaid.errors.PlaidCause(message, type, code, display_message, item_id)

Bases: plaid.errors.BaseError

A cause of a Plaid error.

Variables

  • message (str) – A developer-friendly error message. Not safe for programmatic use.

  • type (str) – A broad categorization of the error, corresponding to the error class.

  • code (str) – An error code for programmatic use.

  • display_message (str) – A user-friendly error message. Not safe for programmatic use. May be None.

  • item_id (str) – The item ID.

exception plaid.errors.InvalidRequestError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.PlaidError

The request is malformed and cannot be processed.

exception plaid.errors.InvalidInputError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.PlaidError

The request is correctly formatted, but the values are incorrect.

exception plaid.errors.RateLimitExceededError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.PlaidError

The request is valid but has exceeded established rate limits.

exception plaid.errors.APIError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.PlaidError

Planned maintenance or an API internal server error.

exception plaid.errors.ItemError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.PlaidError

There is invalid information about an item or it is not supported.

exception plaid.errors.InstitutionError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.PlaidError

There are errors for the requested financial institution.

exception plaid.errors.AuthError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.PlaidError

There are errors with verifying or pulling auth numbers data.

exception plaid.errors.AssetReportError(message, type, code, display_message, request_id='', causes=None)

Bases: plaid.errors.PlaidError

There are errors with creating the asset report.

Indices and tables