API Overview

The inbound API, in which the partner services realtime and periodic Plaid events, has two distinct modes — authorization and aggregation. Authorization extends the partner’s authentication frontier to the entire universe of Plaid applications. Aggregation allows the partner to act as a complete source of truth to all Plaid applications where users have connected their accounts.

The API also provides partners methods to enumerate Plaid applications connected to user accounts, and to drive UIs which empower users to manage those connections. Lastly, the API provides mechanisms whereby both Plaid and the partner can notify each other of key events, such as new connected applications, or new transactions available to fetch.

1Before a user connects their accounts to a Plaid-powered app (e.g. Robinhood, Venmo), Plaid has no Item representing that user’s accounts.

2When a user attempts to connect their accounts to a Plaid-powered app, they will need to complete authentication and in some cases select the specific accounts to be connected. Once they successfully complete authentication and authorization, the Item has been created.

3Immediately after the Item is created, Plaid will attempt to fetch the account summaries and full transaction history (2 years) for the Item. Until the full history is fetched, a Plaid developer’s view of the Item may be incomplete. Once this process is complete, Plaid and downstream developers have a full view of the Item. Future apps connecting to this Item will bypass the initial data fetch.

4If Plaid receives a NewTransactionsNotification related to the Item, or if the Item has not received an update after a given timeout period (ideally 24-48 hours) then Plaid responds by initiating an Item update. During this cycle, Plaid will contact the FI’s API and request updates for the Item’s account balances and any other updated details. If the user has connected an app which requires the transaction history, Plaid will also fetch the latest transaction history.

5Once the updates are fetched, the new data is merged back into the Plaid Item and made available to developers. All apps connected to the Item will receive a webhook notifying them of the availability of new data.

In order to understand the core concepts behind the PX API, it’s necessary to introduce the Item Lifecycle. This core concept underlies Plaid’s data access request pattern, and neatly connects all of the various methods and messages described in this API spec. At Item has three core phases, and the transitions into and out of these phases is what governs the API requests that Plaid will send to a partner’s PX API implementation. The three phases are created, idle, and updating.

When a user successfully authenticates their account and connects their Item to a Plaid developer application, an Item comes into existence but has no financial account data associated with it yet. During this time, Plaid only has authentication tokens representing its authority to connect to the API and request such account data, which is what happens during this phase. Plaid will do an initial data fetch, retrieving account names, classifications, balances and other details for the permissioned accounts, as well as transaction history if the connecting use case requires it. Until this data fetch is complete, Plaid may return errors to the developer if they attempt to request account data for the Item. When this phase is complete, the developer will receive a webhook notifying them that the Item is ready.

This is the phase a healthy Item spends most of its life in. The Item is fully populated with the account and transaction data required to serve the use case. As time since the most recent update increases, the data may no longer be current, which leads to the need for a Plaid initiated update cycle.

Once an Item update is triggered, the Plaid backend will call out to the partner’s API implementation to request account summary and transaction updates for all authorized application use cases. These updates will be requested across the entire Item, i.e. all accounts, even when only one account has new activity. The updates will be merged into Plaid’s Item and will be reflected when the Item returns to an idle state.