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.
notificationsrequired[object] A list of per-user, per-account notifications, see the NewTransactionSummary section below.
Limit: 2000 notifications per request.
| ||
new_sincerequiredstring 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_tokenstring The token used to identify the item that you received via /item/import |
account_idstring 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
notificationsrequired[object] A list of per-user notifications.
Limit: 10,000 notifications per request
| ||
institution_idstring 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_sincerequiredstring 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_tokenrequiredstring A Plaid access token that can be used to request the authorized products on the imported Item, via the Plaid API. |
account_idstring Account identifier. |
new_openrequiredinteger The number of account open events this notification describes. Minimum: 0 |
new_closerequiredinteger The number of account close events this notification describes. Minimum: 0 |
new_statementrequiredinteger The number of statement period close events. Minimum: 0 |
new_informationrequiredinteger The number of new PII or ownership update events Minimum: 0 |
new_otherrequiredinteger The number of other change events not captured above. Minimum: 0 |
Response
200 OK
The notifications were received and are valid.