Statements
API reference for Statements endpoints and webhooks
For how-to guidance, see the Statements documentation.
| Endpoint | Description |
|---|---|
/statements/list | Get a list of statements available to download |
/statements/download | Download a single bank statement |
/statements/refresh | Trigger on-demand statement extractions |
| Webhook Name | Description |
|---|---|
STATEMENTS_REFRESH_COMPLETE | Statements refresh completed |
Endpoints
/statements/list
Retrieve a list of all statements associated with an item.
The /statements/list endpoint retrieves a list of all statements associated with an item.
Request fields
access_tokenrequiredstring
The access token associated with the Item data is being requested for.
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./statements/list
const listRequest: StatementsListRequest = {
access_token: access_token,
};
const listResponse = await plaidClient.statementsList(listRequest);
accounts = listResponse.accounts;
statements = listResponse.accounts[0].statements;
Response fields
accounts[object]
account_idstring
Plaid's unique identifier for the account.
account_maskstring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
account_namestring
The name of the account, either assigned by the user or by the financial institution itself.
account_official_namestring
The official name of the account as given by the financial institution.
account_subtypestring
The subtype of the account. For a full list of valid types and subtypes, see the Account schema.
account_typestring
The type of account. For a full list of valid types and subtypes, see the Account schema.
statements[object]
The list of statements' metadata associated with this account.
statement_idstring
Plaid's unique identifier for the statement.
date_postednullablestring
Date when the statement was posted by the FI, if known
Format:
date monthinteger
Month of the year. Possible values: 1 through 12 (January through December).
yearinteger
The year of statement.
Minimum:
2010 institution_idstring
The Plaid Institution ID associated with the Item.
institution_namestring
The name of the institution associated with 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.request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Response Object
{
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
"institution_id": "ins_3",
"institution_name": "Chase",
"accounts": [
{
"account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
"account_mask": "0000",
"account_name": "Plaid Saving",
"account_official_name": "Plaid Silver Standard 0.1% Interest Saving",
"account_subtype": "savings",
"account_type": "depository",
"statements": [
{
"statement_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"month": 5,
"year": 2023,
"date_posted": "2023-05-01"
}
]
}
],
"request_id": "eYupqX1mZkEuQRx"
}/statements/download
Retrieve a single statement.
The /statements/download endpoint retrieves a single statement PDF in binary format. The response will contain a Plaid-Content-Hash header containing a SHA 256 checksum of the statement. This can be used to verify that the file being sent by Plaid is the same file that was downloaded to your system.
Request fields
access_tokenrequiredstring
The access token associated with the Item data is being requested for.
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.statement_idrequiredstring
Plaid's unique identifier for the statements.
/statements/download
let downloadRequest: StatementsDownloadRequest = {
access_token: accessToken,
statement_id: statement.statement_id,
};
let downloadResponse = await plaidClient.statementsDownload(
downloadRequest,
{responseType: 'arraybuffer'},
);
let pdf = downloadResponse.data.toString('base64');
Response
This endpoint returns a single statement, exactly as provided by the financial institution, in the form of binary PDF data.
/statements/refresh
Refresh statements data.
/statements/refresh initiates an on-demand extraction to fetch the statements for the provided dates.
Request fields
access_tokenrequiredstring
The access token associated with the Item data is being requested for.
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.start_daterequiredstring
The start date for statements, in "YYYY-MM-DD" format, e.g. "2023-08-30". To determine whether a statement falls within the specified date range, Plaid will use the statement posted date. The statement posted date is typically either the last day of the statement period, or the following day.
Format:
date end_daterequiredstring
The end date for statements, in "YYYY-MM-DD" format, e.g. "2023-10-30". You can request up to two years of data. To determine whether a statement falls within the specified date range, Plaid will use the statement posted date. The statement posted date is typically either the last day of the statement period, or the following day.
Format:
date /statements/refresh
const refreshRequest: StatementsRefreshRequest = {
access_token: accessToken,
start_date: '2023-11-01',
end_date: '2024-02-01',
};
const refreshResponse = await plaidClient.statementsRefresh(refreshRequest);
Response fields
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Response Object
{
"request_id": "eYupqX1mZkEuQRx"
}Webhooks
Statement webhooks are sent to indicate that statements refresh has finished processing. All webhooks related to statements have a webhook_type of STATEMENTS.
STATEMENTS_REFRESH_COMPLETE
Fired when refreshed statements extraction is completed or failed to be completed. Triggered by calling /statements/refresh.
Properties
webhook_typestring
STATEMENTSwebhook_codestring
STATEMENTS_REFRESH_COMPLETEitem_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.resultstring
The result of the statement refresh extraction
SUCCESS: The statements were successfully extracted and can be listed via /statements/list/ and downloaded via /statements/download/.FAILURE: The statements failed to be extracted.Possible values:
SUCCESS, FAILUREenvironmentstring
The Plaid environment the webhook was sent from
Possible values:
sandbox, productionAPI Object
{
"webhook_type": "STATEMENTS",
"webhook_code": "STATEMENTS_REFRESH_COMPLETE",
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
"result": "SUCCESS",
"environment": "production"
}