Item endpoints

API reference for retrieving and deleting Items

Endpoints
/item/getRetrieve an Item
/item/removeRemove an Item
/item/webhook/updateUpdate a webhook URL
See also
/sandbox/public_token/createCreate a test Item (Sandbox only)
/sandbox/item/reset_loginForce an Item into an error state (Sandbox only)
/sandbox/item/set_verification_statusSet verification status (Sandbox only)
/sandbox/item/fire_webhookFire a test webhook (Sandbox only)
/item/access_token/invalidateRotate an access token without deleting the Item
Webhooks
ERRORItem has entered an error state
LOGIN_REPAIREDItem has healed from ITEM_LOGIN_REQUIRED without update mode
NEW_ACCOUNTS_AVAILABLENew account detected for an Item
PENDING_EXPIRATIONItem access is about to expire
USER_PERMISSION_REVOKEDThe user has revoked access to an Item
USER_ACCOUNT_REVOKEDThe user has revoked access to an account
WEBHOOK_UPDATE_ACKNOWLEDGEDItem webhook URL updated
SESSION_FINISHEDThe user has completed a Hosted Link session

Endpoints

For Item endpoints related to Item tokens, see Token endpoints.

/item/get

Retrieve an Item

Returns information about the status of an Item.

item/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
1const request: ItemGetRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.itemGet(request);
6  const item = response.data.item;
7  const status = response.data.status;
8} catch (error) {
9  // handle error
10}
item/get

Response fields and example

item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity
products
[string]
A list of products added to the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
status
nullableobject
An object with information about the status of the Item.
investments
nullableobject
Information about the last successful and failed investments update for the Item.
last_successful_update
nullablestring
ISO 8601 timestamp of the last successful investments update for the Item. The status will update each time Plaid successfully connects with the institution, regardless of whether any new data is available in the update.

Format: date-time
last_failed_update
nullablestring
ISO 8601 timestamp of the last failed investments update for the Item. The status will update each time Plaid fails an attempt to connect with the institution, regardless of whether any new data is available in the update.

Format: date-time
transactions
nullableobject
Information about the last successful and failed transactions update for the Item.
last_successful_update
nullablestring
ISO 8601 timestamp of the last successful transactions update for the Item. The status will update each time Plaid successfully connects with the institution, regardless of whether any new data is available in the update.

Format: date-time
last_failed_update
nullablestring
ISO 8601 timestamp of the last failed transactions update for the Item. The status will update each time Plaid fails an attempt to connect with the institution, regardless of whether any new data is available in the update.

Format: date-time
last_webhook
nullableobject
Information about the last webhook fired for the Item.
sent_at
nullablestring
ISO 8601 timestamp of when the webhook was fired.

Format: date-time
code_sent
nullablestring
The last webhook code sent.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "item": {
3    "available_products": [
4      "balance",
5      "auth"
6    ],
7    "billed_products": [
8      "identity",
9      "transactions"
10    ],
11    "error": null,
12    "institution_id": "ins_109508",
13    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
14    "update_type": "background",
15    "webhook": "https://plaid.com/example/hook",
16    "consent_expiration_time": null
17  },
18  "status": {
19    "transactions": {
20      "last_successful_update": "2019-02-15T15:52:39Z",
21      "last_failed_update": "2019-01-22T04:32:00Z"
22    },
23    "last_webhook": {
24      "sent_at": "2019-02-15T15:53:00Z",
25      "code_sent": "DEFAULT_UPDATE"
26    }
27  },
28  "request_id": "m8MDnv9okwxFNBV"
29}

/item/remove

Remove an Item

The /item/remove endpoint allows you to remove an Item. Once removed, the access_token, as well as any processor tokens or bank account tokens associated with the Item, is no longer valid and cannot be used to access any data that was associated with the Item.
Note that in the Development environment, issuing an /item/remove request will not decrement your live credential count. To increase your credential account in Development, contact Support.
Also note that for certain OAuth-based institutions, an Item removed via /item/remove may still show as an active connection in the institution's OAuth permission manager.
API versions 2019-05-29 and earlier return a removed boolean as part of the response.

item/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
1const request: ItemRemoveRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.itemRemove(request);
6  // The Item was removed, access_token is now invalid
7} catch (error) {
8  // handle error
9}
10
11// The Item was removed, access_token is now invalid
item/remove

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "m8MDnv9okwxFNBV"
3}

/item/webhook/update

Update Webhook URL

The POST /item/webhook/update allows you to update the webhook URL associated with an Item. This request triggers a WEBHOOK_UPDATE_ACKNOWLEDGED webhook to the newly specified webhook URL.

item/webhook/update

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
webhook
string
The new webhook URL to associate with the Item. To remove a webhook from an Item, set to null.
Select group for content switcher
1// Update the webhook associated with an Item
2const request: ItemWebhookUpdateRequest = {
3  access_token: accessToken,
4  webhook: 'https://example.com/updated/webhook',
5};
6try {
7  const response = await plaidClient.itemWebhookUpdate(request);
8  // A successful response indicates that the webhook has been
9  // updated. An acknowledgement webhook will also be fired.
10  const item = response.data.item;
11} catch (error) {
12  // handle error
13}
item/webhook/update

Response fields and example

item
object
Metadata about the Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
error
nullableobject
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity
products
[string]
A list of products added to the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity
consented_products
[string]
A list of products that have gone through consent collection for the Item. Only present for those enabled in the Data Transparency beta. If you are not enrolled in Data Transparency, this field is not used.

Possible values: assets, auth, balance, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, deposit_switch, standing_orders, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity
consent_expiration_time
nullablestring
The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.
Note - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "item": {
3    "available_products": [
4      "balance",
5      "identity",
6      "payment_initiation",
7      "transactions"
8    ],
9    "billed_products": [
10      "assets",
11      "auth"
12    ],
13    "consent_expiration_time": null,
14    "error": null,
15    "institution_id": "ins_117650",
16    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
17    "update_type": "background",
18    "webhook": "https://www.genericwebhookurl.com/webhook"
19  },
20  "request_id": "vYK11LNTfRoAMbj"
21}

Webhooks

Webhooks are used to communicate changes to an Item, such as an updated webhook, or errors encountered with an Item. The error typically requires user action to resolve, such as when a user changes their password. All Item webhooks have a webhook_type of ITEM.

ERROR

Fired when an error is encountered with an Item. The error can be resolved by having the user go through Link’s update mode.

webhook_type
string
ITEM
webhook_code
string
ERROR
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "ERROR",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": {
6    "display_message": null,
7    "error_code": "ITEM_LOGIN_REQUIRED",
8    "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
9    "error_type": "ITEM_ERROR",
10    "status": 400
11  },
12  "environment": "production"
13}

LOGIN_REPAIRED

Fired when an Item has exited the ITEM_LOGIN_REQUIRED state without the user having gone through the update mode flow in your app (this can happen if the user completed the update mode in a different app). If you have messaging that tells the user to complete the update mode flow, you should silence this messaging upon receiving the LOGIN_REPAIRED webhook.

webhook_type
string
ITEM
webhook_code
string
LOGIN_REPAIRED
item_id
string
The item_id of the Item associated with this webhook, warning, or error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "LOGIN_REPAIRED",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "environment": "production"
6}

NEW_ACCOUNTS_AVAILABLE

Fired when Plaid detects a new account for Items created or updated with Account Select v2. Upon receiving this webhook, you can prompt your users to share new accounts with you through Account Select v2 update mode.

webhook_type
string
ITEM
webhook_code
string
NEW_ACCOUNTS_AVAILABLE
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "NEW_ACCOUNTS_AVAILABLE",
4  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
5  "error": null,
6  "environment": "production"
7}

PENDING_EXPIRATION

Fired when an Item’s access consent is expiring in 7 days. Some Items have explicit expiration times and we try to relay this when possible to reduce service disruption. This can be resolved by having the user go through Link’s update mode.

webhook_type
string
ITEM
webhook_code
string
PENDING_EXPIRATION
item_id
string
The item_id of the Item associated with this webhook, warning, or error
consent_expiration_time
string
The date and time at which the Item's access consent will expire, in ISO 8601 format

Format: date-time
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "PENDING_EXPIRATION",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "consent_expiration_time": "2020-01-15T13:25:17.766Z",
6  "environment": "production"
7}

USER_PERMISSION_REVOKED

The USER_PERMISSION_REVOKED webhook may be fired when an end user has used either the my.plaid.com portal or the financial institution’s OAuth consent portal to revoke the permission that they previously granted to access an Item. This webhook is not guaranteed to always be fired upon consent revocation, since some institutions’ consent portals do not trigger this webhook. Once access to an Item has been revoked, it cannot be restored. If the user subsequently returns to your application, a new Item must be created for the user.
Note that when using ACH flows with Chase Items specifically, the account number provided by Plaid will no longer work for creating transfers once user permission has been revoked. If you receive this webhook for a Chase Item, you should not create any new ACH transfers for that Item, as they will be returned.

webhook_type
string
ITEM
webhook_code
string
USER_PERMISSION_REVOKED
item_id
string
The item_id of the Item associated with this webhook, warning, or error
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "USER_PERMISSION_REVOKED",
4  "error": {
5    "error_code": "USER_PERMISSION_REVOKED",
6    "error_message": "the holder of this account has revoked their permission for your application to access it",
7    "error_type": "ITEM_ERROR",
8    "status": 400
9  },
10  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
11  "environment": "production"
12}

USER_ACCOUNT_REVOKED

The USER_ACCOUNT_REVOKED webhook is fired when an end user has revoked access to their account on the Data Provider's portal. This webhook is currently sent only for Chase Items, but may be sent in the future for other financial institutions that allow account-level permissions revocation through their portals.
If you are using Auth and receive this webhook for a Chase Item, this webhook indicates that the TAN associated with the revoked account is no longer valid and cannot be used to create new transfers. You should not create new ACH transfers for the account that was revoked until access has been re-granted.
You can request the user to re-grant access to their account by sending them through update mode. Alternatively, they may re-grant access directly through the Data Provider's portal.
After the user has re-granted access, Auth customers should call the auth endpoint again to obtain the new TAN.

webhook_type
string
ITEM
webhook_code
string
USER_ACCOUNT_REVOKED
item_id
string
The item_id of the Item associated with this webhook, warning, or error
account_id
string
The external account ID of the affected account
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "`ITEM`",
3  "webhook_code": "USER_ACCOUNT_REVOKED",
4  "error": {
5    "error_code": "ACCESS_NOT_GRANTED",
6    "error_message": "the user has revoked the account permissions for your application to access it",
7    "error_type": "ITEM_ERROR",
8    "status": 400
9  },
10  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
11  "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
12  "environment": "production"
13}

WEBHOOK_UPDATE_ACKNOWLEDGED

Fired when an Item's webhook is updated. This will be sent to the newly specified webhook.

webhook_type
string
ITEM
webhook_code
string
WEBHOOK_UPDATE_ACKNOWLEDGED
item_id
string
The item_id of the Item associated with this webhook, warning, or error
new_webhook_url
string
The new webhook URL
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": null,
6  "new_webhook_url": "https://plaid.com/example/webhook",
7  "environment": "production"
8}

SESSION_FINISHED

Contains the state of a completed Link session, along with the public token if available.

webhook_type
string
LINK
webhook_code
string
SESSION_FINISHED
status
string
The final status of the Link session. Will always be "SUCCESS" or "EXITED".
link_session_id
string
The identifier for the Link session.
link_token
string
The link token used to create the Link session.
public_token
string
The public token generated by the Link session.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "LINK",
3  "webhook_code": "SESSION_FINISHED",
4  "status": "SUCCESS",
5  "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",
6  "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
7  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
8  "environment": "sandbox"
9}