Item endpoints

API reference for retrieving and deleting Items

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_idstring
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.
secretstring
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_tokenrequiredstring
The access token associated with the Item data is being requested for.
1
2
3
4
5
6
const response = await client.getItem(accessToken).catch((err) => {
// handle error
});
const item = response.item;
const status = response.status;
item/get

Response fields and example

itemobject
Metadata about the Item.
item_idstring
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_idnullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhooknullablestring
The URL registered to receive webhooks for the Item.
errornullableobject
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. Error fields will be null if no error has occurred.
error_typestring
A broad categorization of the error. Safe for programatic 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
error_codestring
The particular error code. Safe for programmatic use.
error_messagestring
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagenullablestring
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_idstring
A unique identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causesarray
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.
statusnullablenumber
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_urlnullablestring
The URL of a Plaid documentation page with more information about the error
suggested_actionnullablestring
Suggested steps for resolving the error
available_products[string]
A list of products available for the Item that have not yet been accessed.
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
billed_products[string]
A list of products that have been billed for the Item. Note - billed_products is populated in all environments but only requests in Production are billed.
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
consent_expiration_timenullablestring
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.
update_typestring
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
requires_user_authentication - Item requires user interaction to be updated

Possible values: background, requires_user_authentication
statusnullableobject
An object with information about the status of the Item.
investmentsnullableobject
Information about the last successful and failed investments update for the Item.
last_successful_updatenullablestring
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.
last_failed_updatenullablestring
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.
transactionsnullableobject
Information about the last successful and failed transactions update for the Item.
last_successful_updatenullablestring
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.
last_failed_updatenullablestring
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.
last_webhooknullableobject
Information about the last webhook fired for the Item.
sent_atnullablestring
ISO 8601 timestamp of when the webhook was fired.
code_sentnullablestring
The last webhook code sent.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"item": {
"available_products": [
"balance",
"auth"
],
"billed_products": [
"identity",
"transactions"
],
"error": null,
"institution_id": "ins_109508",
"item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
"update_type": "background",
"webhook": "https://plaid.com/example/hook",
"consent_expiration_time": null
},
"status": {
"transactions": {
"last_successful_update": "2019-02-15T15:52:39.000Z",
"last_failed_update": "2019-01-22T04:32:00.000Z"
},
"last_webhook": {
"sent_at": "2019-02-15T15:53:00.000Z",
"code_sent": "DEFAULT_UPDATE"
}
},
"request_id": "m8MDnv9okwxFNBV"
}

/item/remove

Remove an Item

The /item/remove endpoint allows you to remove an Item. Once removed, the access_token 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.

item/remove

Request fields and example

client_idstring
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.
secretstring
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_tokenrequiredstring
The access token associated with the Item data is being requested for.
1
2
3
4
5
6
const response = await client.removeItem(accessToken).catch((err) => {
// handle error
});
// The Item was removed, access_token is now invalid
assert(response.removed, true);
item/remove

Response fields and example

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

/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_idstring
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.
secretstring
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_tokenrequiredstring
The access token associated with the Item data is being requested for.
webhookrequiredstring
The new webhook URL to associate with the Item.
1
2
3
4
5
6
7
8
9
10
// Update the webhook associated with an Item
const response = await client
.updateItemWebhook(accessToken, 'https://example.com/updated/webhook')
.catch((err) => {
// handle error
});
// A successful response indicates that the webhook has been
// updated. An acknowledgement webhook will also be fired.
const item = result.item;
item/webhook/update

Response fields and example

itemobject
Metadata about the Item.
item_idstring
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_idnullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created via Same Day Micro-deposits.
webhooknullablestring
The URL registered to receive webhooks for the Item.
errornullableobject
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. Error fields will be null if no error has occurred.
error_typestring
A broad categorization of the error. Safe for programatic 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
error_codestring
The particular error code. Safe for programmatic use.
error_messagestring
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagenullablestring
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_idstring
A unique identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causesarray
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.
statusnullablenumber
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_urlnullablestring
The URL of a Plaid documentation page with more information about the error
suggested_actionnullablestring
Suggested steps for resolving the error
available_products[string]
A list of products available for the Item that have not yet been accessed.
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
billed_products[string]
A list of products that have been billed for the Item. Note - billed_products is populated in all environments but only requests in Production are billed.
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
consent_expiration_timenullablestring
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.
update_typestring
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
requires_user_authentication - Item requires user interaction to be updated

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