Statements

API reference for Statements endpoints and webhooks

For how-to guidance, see the Statements documentation.

EndpointDescription
/statements/listGet a list of statements available to download
/statements/downloadDownload a single bank statement
/statements/refreshTrigger on-demand statement extractions
Webhook NameDescription
STATEMENTS_REFRESH_COMPLETEStatements 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.

statements/list

Response fields

access_token
requiredstring
The access token associated with the Item data is being requested for.
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.
1const listRequest: StatementsListRequest = {
2  access_token: access_token,
3};
4const listResponse = await plaidClient.statementsList(listRequest);
5accounts = listResponse.accounts;
6statements = listResponse.accounts[0].statements;
statements/list

Response fields and example

accounts
[object]
account_id
string
Plaid's unique identifier for the account.
account_mask
string
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_name
string
The name of the account, either assigned by the user or by the financial institution itself.
account_official_name
string
The official name of the account as given by the financial institution.
account_subtype
string
The subtype of the account. For a full list of valid types and subtypes, see the Account schema.
account_type
string
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_id
string
Plaid's unique identifier for the statement.
date_posted
nullablestring
Date when the statement was posted by the FI, if known

Format: date
month
integer
Month of the year. Possible values: 1 through 12 (January through December).
year
integer
The year of statement.

Minimum: 2010
institution_id
string
The Plaid Institution ID associated with the Item.
institution_name
string
The name of the institution associated with 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.
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_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
3  "institution_id": "ins_3",
4  "institution_name": "Chase",
5  "accounts": [
6    {
7      "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
8      "account_mask": "0000",
9      "account_name": "Plaid Saving",
10      "account_official_name": "Plaid Silver Standard 0.1% Interest Saving",
11      "account_subtype": "savings",
12      "account_type": "depository",
13      "statements": [
14        {
15          "statement_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
16          "month": 5,
17          "year": 2023,
18          "date_posted": "2023-05-01"
19        }
20      ]
21    }
22  ],
23  "request_id": "eYupqX1mZkEuQRx"
24}

/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.

statements/download

Response fields

access_token
requiredstring
The access token associated with the Item data is being requested for.
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.
statement_id
requiredstring
Plaid's unique identifier for the statements.
1let downloadRequest: StatementsDownloadRequest = {
2  access_token: accessToken,
3  statement_id: statement.statement_id,
4};
5let downloadResponse = await plaidClient.statementsDownload(
6  downloadRequest,
7  {responseType: 'arraybuffer'},
8);
9let 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.

statements/refresh

Response fields

access_token
requiredstring
The access token associated with the Item data is being requested for.
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.
start_date
requiredstring
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_date
requiredstring
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 
1const refreshRequest: StatementsRefreshRequest = {
2  access_token: accessToken,
3  start_date: '2023-11-01',
4  end_date: '2024-02-01',
5};
6const refreshResponse = await plaidClient.statementsRefresh(refreshRequest);
statements/refresh

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": "eYupqX1mZkEuQRx"
3}

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.

webhook_type
string
STATEMENTS
webhook_code
string
STATEMENTS_REFRESH_COMPLETE
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.
result
string
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, FAILURE
environment
string
The Plaid environment the webhook was sent from

Possible values: sandbox, production
1{
2  "webhook_type": "STATEMENTS",
3  "webhook_code": "STATEMENTS_REFRESH_COMPLETE",
4  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
5  "result": "SUCCESS",
6  "environment": "production"
7}