Statements 
===========

#### API reference for Statements endpoints and webhooks 

For how-to guidance, see the [Statements documentation](https://plaid.com/docs/statements/index.html.md) .

| Endpoint | Description |
| --- | --- |
| [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) | Get a list of statements available to download |
| [/statements/download](https://plaid.com/docs/api/products/statements/index.html.md#statementsdownload) | Download a single bank statement |
| [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) | Trigger on-demand statement extractions |

| Webhook Name | Description |
| --- | --- |
| [STATEMENTS\_REFRESH\_COMPLETE](https://plaid.com/docs/api/products/statements/index.html.md#statements_refresh_complete) | Statements refresh completed |

### Endpoints 

\=\*=\*=\*=

#### /statements/list 

#### Retrieve a list of all statements associated with an Item. 

The [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) endpoint retrieves a list of all statements associated with an Item.

#### Request fields 

required, string

The access token associated with the Item for which data is being requested.

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.

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.

```python
request = StatementsListRequest(access_token=access_token)
response = client.statements_list(request)
accounts = response['accounts']
statements = accounts[0]['statements']

```

```bash
curl -X POST https://sandbox.plaid.com/statements/list \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": "${PLAID_CLIENT_ID}",
   "secret": "${PLAID_SECRET}",
   "access_token": String
 }'

```

```java
StatementsListRequest statementsListRequest = new StatementsListRequest().accessToken(accessToken);
Response statementsListResponse = client.statementsList(statementsListRequest).execute();
List accounts = statementsListResponse.body().getAccounts();
List statements = accounts.get(0).getStatements();

```

```ruby
statements_list_request = Plaid::StatementsListRequest.new
statements_list_request.access_token = access_token
response = client.statements_list(statements_list_request)
accounts = response.accounts
statements = accounts[0].statements

```

```node
const listRequest: StatementsListRequest = {
  access_token: access_token,
};
const listResponse = await plaidClient.statementsList(listRequest);
accounts = listResponse.data.accounts;
statements = listResponse.data.accounts[0].statements;

```

```go
statementsListRequest := plaid.NewStatementsListRequest(accessToken)
statementsListResponse, _, err := client.PlaidApi.StatementsList(ctx).StatementsListRequest(*statementsListRequest).Execute()
accounts := statementsListResponse.GetAccounts()
statements := accounts[0].GetStatements()

```

#### Response fields 

\[object\]

string

Plaid's unique identifier for the account.

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.

string

The name of the account, either assigned by the user or by the financial institution itself.

string

The official name of the account as given by the financial institution.

string

The subtype of the account. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

string

The type of account. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) .

\[object\]

The list of statements' metadata associated with this account.

string

Plaid's unique identifier for the statement.

nullable, string

Date when the statement was posted by the FI, if known

Format: `date`

integer

Month of the year. Possible values: 1 through 12 (January through December).

integer

The year of the statement, e.g. 2024.

Minimum: `2010`

string

The Plaid Institution ID associated with the Item.

string

The name of the institution associated with the Item.

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.

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "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](https://plaid.com/docs/api/products/statements/index.html.md#statementsdownload) 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 

required, string

The access token associated with the Item for which data is being requested.

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.

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.

required, string

Plaid's unique identifier for the statement.

```python
request = StatementsDownloadRequest(
  access_token=access_token,
  statement_id=statement_id,
)
pdf, status_code, headers = client.statements_download(request, _return_http_data_only=False)

```

```bash
curl -X POST https://sandbox.plaid.com/statements/download \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": "${PLAID_CLIENT_ID}",
   "secret": "${PLAID_SECRET}",
   "access_token": String,
   "statement_id": String
 }'

```

```java
StatementsDownloadRequest statementsDownloadRequest = new StatementsDownloadRequest().accessToken(accessToken).statementId(statementID);
Response response = client.statementsDownload(statementsDownloadRequest).execute();
byte[] pdf = response.body().bytes();

```

```ruby
statements_download_request = Plaid::StatementsDownloadRequest.new
statements_download_request.access_token = access_token
statements_download_request.statement_id = statement.statement_id
pdf, status_code, headers = client.statements_download_with_http_info(statements_download_request)

```

```node
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');

```

```go
downloadRequest := plaid.NewStatementsDownloadRequest(accessToken, statement.GetStatementId())
_, downloadResponse, err := client.PlaidApi.StatementsDownload(ctx).StatementsDownloadRequest(*downloadRequest).Execute()
if err != nil {
  return err
}
pdf, err := io.ReadAll(downloadResponse.Body)

```

##### 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](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) initiates an on-demand extraction to fetch the statements for the provided dates.

#### Request fields 

required, string

The access token associated with the Item for which data is being requested.

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.

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.

required, string

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`

required, string

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`

```python
request = StatementsRefreshRequest(
    access_token=access_token,
    start_date=date.today() - timedelta(days=90),
    end_date=date.today(),
)
response = client.statements_refresh(request)

```

```bash
curl -X POST https://sandbox.plaid.com/statements/refresh \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": "${PLAID_CLIENT_ID}",
   "secret": "${PLAID_SECRET}",
   "access_token": String,
   "start_date": "2023-08-01",
   "end_date": "2023-11-01"
 }'

```

```java
StatementsRefreshRequest statementsRefreshRequest = new StatementsRefreshRequest().accessToken(accessToken).startDate(LocalDate.parse(startDate)).endDate(LocalDate.parse(endDate));
response = client.statementsRefresh(statementsRefreshRequest).execute();

```

```ruby
statements_refresh_request = Plaid::StatementsRefreshRequest.new
statements_refresh_request.access_token = access_token
statements_refresh_request.start_date = Date.today.prev_year
statements_refresh_request.end_date = Date.today.prev_month(10)
response = client.statements_refresh(statements_refresh_request)

```

```node
const refreshRequest: StatementsRefreshRequest = {
  access_token: accessToken,
  start_date: '2023-11-01',
  end_date: '2024-02-01',
};
const refreshResponse = await plaidClient.statementsRefresh(refreshRequest);

```

```go
startDate, endDate := "2023-11-01", "2024-01-01"
refreshRequest := plaid.NewStatementsRefreshRequest(accessToken, startDate, endDate)
refreshResponse, _, err := client.PlaidApi.StatementsRefresh(ctx).StatementsRefreshRequest(*refreshRequest).Execute()

```

#### Response fields 

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "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](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) .

#### Properties 

string

`STATEMENTS`

string

`STATEMENTS_REFRESH_COMPLETE`

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.

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`

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "STATEMENTS",
  "webhook_code": "STATEMENTS_REFRESH_COMPLETE",
  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
  "result": "SUCCESS",
  "environment": "production"
}
```