Plaid logo
Exchange
ALL DOCS

API reference

  • Authentication
  • Aggregation
  • Notification
  • Errors and Conditions
Open nav
Plaid logoExchange
Plaid.comGet Started

Notification API Reference

This API enables partners to notify Plaid about significant changes to the status of an item. Notifications are asynchronous events: successful responses only indicate that Plaid acknowledges the notification, and explicitly do not indicate that any associated side effect actions were completed.

Account Activity Notification API

New transactions ready

POST /items/transactions/notify
Request
NewTransactionsNotification

Indicate that new transactions are available for the given user IDs. Be aware that Plaid may initiate an aggregation call to fetch transactions shortly after receiving this notification, see Retrieve Transactions API method.
Extends PlaidAuthenticateRequest
Note: For optimal user experience, the new_since value should be less than two minutes from the time of notification.

notifications
[object]
A list of per-user, per-account notifications, see the NewTransactionSummary section below. Limit: 2000 notifications per request.
access_token
string
The token used to identify the item that you received via /item/import
account_id
string
Account identifier obtained from /item/import.
new_since
string
The age of the earliest transaction counted in this notification. This value indicates that the Plaid Exchange Partner has waited for a certain period of time before sending this notification, e.g. to batch up multiple requests and minimize processing.

Format: date
NewTransactionsSummary

Description of the user's unaggregated transaction activity.

access_token
string
The token used to identify the item that you received via /item/import
account_id
string
Account identifier obtained from /item/import.
Response
200 OK

The notifications were received and are valid.

400 Bad Request

Data is malformed. No transactions will be updated.

401 Unauthorized

Secret could not be validated. No transactions will be updated.

429 Too Many Requests

Exceeded the number of calls in a specified time. No transactions will be updated.

New account activity

POST /items/accounts/notify

Indicate that the given user IDs have undergone account state change (new account, closed account, statement ready, etc).

Request
NewAccountActivityNotification

Notification of changes in account state or user identity.
Extends PlaidAuthenticateRequest

notifications
[object]
A list of per-user notifications. Limit: 10,000 notifications per request
access_token
string
The token used to identify the item that you received via /item/import
account_id
string
Account identifier obtained from /item/import.
institution_id
string
For implementations serving multiple institutions, this is the pre-shared identifier for the institution where these user’s accounts are held. NOTE A request may describe only one institution’s users.
new_since
string
The age of the earliest change counted in this notification. This value permits the partner to communicate to Plaid that it has waited for a certain period of time before sending this notification, e.g. to batch up multiple requests and minimize processing.

Format: date
NewAccountActivitySummary

Description of a user‘s account change activity.

access_token
string
A Plaid access token that can be used to request the authorized products on the imported Item, via the Plaid API.
account_id
string
Account identifier.
new_open
integer
The number of account open events this notification describes.

Minimum: 0
new_close
integer
The number of account close events this notification describes.

Minimum: 0
new_statement
integer
The number of statement period close events.

Minimum: 0
new_information
integer
The number of new PII or ownership update events

Minimum: 0
new_other
integer
The number of other change events not captured above.

Minimum: 0
Response
200 OK

The notifications were received and are valid.