Items

API reference for managing Items

Endpoints
/item/getRetrieve an Item
/item/removeRemove an Item
/item/webhook/updateUpdate a webhook URL
/item/public_token/exchangeExchange a public token from Link for an access token
/item/access_token/invalidateRotate an access token without deleting the Item
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 Auth verification status (Sandbox only)
/sandbox/item/fire_webhookFire a test webhook (Sandbox only)
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_DISCONNECTItem access is about to expire (US/CA) or end
PENDING_EXPIRATIONItem access is about to expire (UK/EU)
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

Token exchange flow

Many API calls to Plaid product endpoints require an access_token. An access_token corresponds to an Item, which is a login at a financial institution. To obtain an access_token:

  1. Obtain a link_token by calling /link/token/create.
  2. Initialize Link by passing in the link_token. When your user completes the Link flow, Link will pass back a public_token via the onSuccess callback. For more information on initializing and receiving data back from Link, see the Link documentation.
  3. Exchange the public_token for an access_token by calling /item/public_token/exchange.

The access_token can then be used to call Plaid endpoints and obtain information about an Item.

In addition to the primary flow, several other token flows exist. The Link update mode flow allows you to update an access_token that has stopped working. The Sandbox testing environment also offers the /sandbox/public_token/create endpoint, which allows you to create a public_token without using Link. And the Hosted Link and Multi-Item Link (coming soon) flows provide the public_token via the backend rather than using the frontend onSuccess callback.

Endpoints

/item/get

Retrieve an Item

Returns information about the status of an Item.

item/get
Request fields
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 without an institution connection, such as Items created via Same Day Micro-deposits.
institution_name
nullablestring
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
auth_method
nullablestring
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation.
INSTANT_AUTH: The Item's Auth data was provided directly by the user's institution connection.
INSTANT_MATCH: The Item's Auth data was provided via the Instant Match fallback flow.
AUTOMATED_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow.
SAME_DAY_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow.
INSTANT_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow.
DATABASE_MATCH: The Item's Auth data was provided via the Database Match flow.
DATABASE_INSIGHTS: The Item's Auth data was provided via the Database Insights flow.
TRANSFER_MIGRATED: The Item's Auth data was provided via /transfer/migrate_account.
INVESTMENTS_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow.

Possible values: INSTANT_AUTH, INSTANT_MATCH, AUTOMATED_MICRODEPOSITS, SAME_DAY_MICRODEPOSITS, INSTANT_MICRODEPOSITS, DATABASE_MATCH, DATABASE_INSIGHTS, TRANSFER_MIGRATED, INVESTMENTS_FALLBACK
error
nullableobject
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
nullablestring
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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 this 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, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
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, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
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, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
consented_products
[string]
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product.

Possible values: assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, transactions, income, income_verification, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity, cra_base_report, cra_income_insights, cra_partner_insights, cra_cashflow_insights, layer
consent_expiration_time
nullablestring
The date and time at which the Item's access consent will expire, in ISO 8601 format

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
created_at
string
The date and time when the Item was created, in ISO 8601 format.

Format: date-time
consented_use_cases
[string]
A list of use cases that the user has consented to for the Item via Data Transparency Messaging.
You can see the full list of use cases or update the list of use cases to request at any time via the Link Customization section of the Plaid Dashboard.
consented_data_scopes
[string]
A list of data scopes that the user has consented to for the Item via Data Transparency Messaging. These are based on the consented_products; see the full mapping of data scopes and products.

Possible values: account_and_balance_info, contact_info, account_and_routing_numbers, transactions, credit_and_loans, investments, bank_statements, risk_info
status
nullableobject
Information about the last successful and failed transactions update for 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. This field does not reflect transactions updates performed by non-Transactions products (e.g. Signal).

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. This field does not reflect transactions updates performed by non-Transactions products (e.g. Signal).

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    "created_at": "2019-01-22T04:32:00Z",
4    "available_products": [
5      "balance",
6      "auth"
7    ],
8    "billed_products": [
9      "identity",
10      "transactions"
11    ],
12    "products": [
13      "identity",
14      "transactions"
15    ],
16    "error": null,
17    "institution_id": "ins_109508",
18    "institution_name": "First Platypus Bank",
19    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
20    "update_type": "background",
21    "webhook": "https://plaid.com/example/hook",
22    "auth_method": null,
23    "consented_products": [
24      "identity",
25      "transactions"
26    ],
27    "consented_data_scopes": [
28      "Account and balance info",
29      "Contact info",
30      "Transactions"
31    ],
32    "consented_use_cases": [
33      "Verify your account",
34      "Track and manage your finances"
35    ],
36    "consent_expiration_time": "2024-03-16T15:53:00Z"
37  },
38  "status": {
39    "transactions": {
40      "last_successful_update": "2019-02-15T15:52:39Z",
41      "last_failed_update": "2019-01-22T04:32:00Z"
42    },
43    "last_webhook": {
44      "sent_at": "2019-02-15T15:53:00Z",
45      "code_sent": "DEFAULT_UPDATE"
46    }
47  },
48  "request_id": "m8MDnv9okwxFNBV"
49}

/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.
Calling /item/remove is a recommended best practice when offboarding users or if a user chooses to disconnect an account linked via Plaid. For subscription products, such as Transactions, Liabilities, and Investments, calling /item/remove is required to end subscription billing for the Item.
In Limited Production, calling /item/remove does not impact the number of remaining Limited Production Items you have available.
Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove access to them specifically using the /asset_report/remove endpoint.
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
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
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 without an institution connection, such as Items created via Same Day Micro-deposits.
institution_name
nullablestring
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
auth_method
nullablestring
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation.
INSTANT_AUTH: The Item's Auth data was provided directly by the user's institution connection.
INSTANT_MATCH: The Item's Auth data was provided via the Instant Match fallback flow.
AUTOMATED_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow.
SAME_DAY_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow.
INSTANT_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow.
DATABASE_MATCH: The Item's Auth data was provided via the Database Match flow.
DATABASE_INSIGHTS: The Item's Auth data was provided via the Database Insights flow.
TRANSFER_MIGRATED: The Item's Auth data was provided via /transfer/migrate_account.
INVESTMENTS_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow.

Possible values: INSTANT_AUTH, INSTANT_MATCH, AUTOMATED_MICRODEPOSITS, SAME_DAY_MICRODEPOSITS, INSTANT_MICRODEPOSITS, DATABASE_MATCH, DATABASE_INSIGHTS, TRANSFER_MIGRATED, INVESTMENTS_FALLBACK
error
nullableobject
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
nullablestring
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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 this 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, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
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, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
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, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
consented_products
[string]
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product.

Possible values: assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, transactions, income, income_verification, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity, cra_base_report, cra_income_insights, cra_partner_insights, cra_cashflow_insights, layer
consent_expiration_time
nullablestring
The date and time at which the Item's access consent will expire, in ISO 8601 format

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    "institution_name": "Royal Bank of Plaid",
17    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
18    "update_type": "background",
19    "webhook": "https://www.genericwebhookurl.com/webhook",
20    "auth_method": "INSTANT_AUTH"
21  },
22  "request_id": "vYK11LNTfRoAMbj"
23}

/item/public_token/exchange

Exchange public token for an access token

Exchange a Link public_token for an API access_token. Link hands off the public_token client-side via the onSuccess callback once a user has successfully created an Item. The public_token is ephemeral and expires after 30 minutes. An access_token does not expire, but can be revoked by calling /item/remove.
The response also includes an item_id that should be stored with the access_token. The item_id is used to identify an Item in a webhook. The item_id can also be retrieved by making an /item/get request.

item/public_token/exchange
Request fields
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.
public_token
requiredstring
Your public_token, obtained from the Link onSuccess callback or /sandbox/item/public_token/create.
Select group for content switcher
1const request: ItemPublicTokenExchangeRequest = {
2  public_token: publicToken,
3};
4try {
5  const response = await plaidClient.itemPublicTokenExchange(request);
6  const accessToken = response.data.access_token;
7  const itemId = response.data.item_id;
8} catch (err) {
9  // handle error
10}
item/public_token/exchange

Response fields and example

access_token
string
The access token associated with the Item data is being requested for.
item_id
string
The item_id value of the Item associated with the returned access_token
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  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
3  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
4  "request_id": "Aim3b"
5}

/item/access_token/invalidate

Invalidate access_token

By default, the access_token associated with an Item does not expire and should be stored in a persistent, secure manner.
You can use the /item/access_token/invalidate endpoint to rotate the access_token associated with an Item. The endpoint returns a new access_token and immediately invalidates the previous access_token.

item/access_token/invalidate
Request fields
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
1// Generate a new access_token for an Item, invalidating the old one
2const request: ItemAccessTokenInvalidateRequest = {
3  access_token: accessToken,
4};
5try {
6  const response = await plaidClient.itemAccessTokenInvalidate(request);
7  // Store the new access_token in a persistent, secure datastore
8  const accessToken = response.data.new_access_token;
9} catch (error) {
10  // handle error
11}
item/access_token/invalidate

Response fields and example

new_access_token
string
The access token associated with the Item data is being requested for.
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  "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
3  "request_id": "m8MDnv9okwxFNBV"
4}

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
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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 this 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: sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "ERROR",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "error": {
6    "display_message": "The user’s OAuth connection to this institution has been invalidated.",
7    "error_code": "ITEM_LOGIN_REQUIRED",
8    "error_code_reason": "OAUTH_INVALID_TOKEN",
9    "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",
10    "error_type": "ITEM_ERROR",
11    "status": 400
12  },
13  "environment": "production"
14}

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: 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. Upon receiving this webhook, you can prompt your users to share new accounts with you through update mode (US/CA only). If the end user has opted not to share new accounts with Plaid via their institution's OAuth settings, Plaid will not detect new accounts and this webhook will not fire. For end user accounts in the EU and UK, upon receiving this webhook, you can prompt your user to re-link their account and then delete the old Item via /item/remove.

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
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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 this 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: 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_DISCONNECT

Fired when an Item is expected to be disconnected. The webhook will currently be fired 7 days before the existing Item is scheduled for disconnection. This can be resolved by having the user go through Link’s update mode. Currently, this webhook is fired only for US or Canadian institutions; in the UK or EU, you should continue to listed for the PENDING_EXPIRATION webhook instead.

webhook_type
string
ITEM
webhook_code
string
PENDING_DISCONNECT
item_id
string
The item_id of the Item associated with this webhook, warning, or error
reason
string
Reason why the item is about to be disconnected. INSTITUTION_MIGRATION: The institution is moving to API or to a different integration. For example, this can occur when an institution moves from a non-OAuth integration to an OAuth integration. INSTITUTION_TOKEN_EXPIRATION: The consent on an Item associated with a US or CA institution is about to expire.

Possible values: INSTITUTION_MIGRATION, INSTITUTION_TOKEN_EXPIRATION
environment
string
The Plaid environment the webhook was sent from

Possible values: sandbox, production
1{
2  "webhook_type": "ITEM",
3  "webhook_code": "PENDING_DISCONNECT",
4  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
5  "reason": "INSTITUTION_MIGRATION",
6  "environment": "production"
7}

PENDING_EXPIRATION

Fired when an Item’s access consent is expiring in 7 days. This can be resolved by having the user go through Link’s update mode. This webhook is fired only for Items associated with institutions in Europe (including the UK); for Items associated with institutions in the US or Canada, see PENDING_DISCONNECT instead.

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: 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 revoked the permission that they previously granted to access an Item. If the end user revoked their permissions through Plaid (such as via the Plaid Portal or by contacting Plaid Support), the webhook will fire. If the end user revoked their permissions directly through the institution, this webhook may not always fire, since some institutions’ consent portals do not trigger this webhook. Upon receiving this webhook, it is recommended to delete any stored data from Plaid associated with the Item. To restore the Item, it can be sent through update mode.
Note that when working with tokenized account numbers with Auth or Transfer, the account number provided by Plaid will no longer work for creating transfers once user permission has been revoked.

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
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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 this 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: 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. Upon receiving this webhook, it is recommended to delete any Plaid-derived data you have stored that is associated with the revoked account.
If you are using Auth and receive this webhook, 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
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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 this 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: 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
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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 this 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: 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}