Request a bank statement

This guide shows you how to request a bank statement through the API, wait while we generate it, and download it. For what a statement contains and which format to choose, see What is a bank statement?.

Before you start

You need:

• An API key with the right role. An API key has the same permissions as the user who created it (see roles). To request statements, the user needs the Manage accounts role. To list and download statements, they need Manage accounts, Accounts and payments viewer, Approve own payments, Approve payments or Request payments.
• The bank account's account-statements-url. It's in the bank account's details, which you get when you open the account or fetch it. The examples below call it $ACCOUNT_STATEMENTS_URL.

How it works

We generate statements in the background, so getting one takes three steps:

1. You request a statement. We create it with the status pending and give you its statement-url.
2. You check the statement until its status is generated. Most statements are ready within a few seconds.
3. You download the document from its statement-download-url.

We don't send a webhook event for statements, so your integration needs to check the statement's status itself. The API reference describes every field.

Step 1: Request a statement

Request a statement by sending a POST to the bank account's account-statements-url, with:

Field	Description
format	griffin-pdf for a PDF statement, or xero-csv for a Xero CSV export.
start-date	The first day the statement covers, as YYYY-MM-DD.
end-date	The last day the statement covers, as YYYY-MM-DD. It must be before today in UK time.

The statement includes both dates. See choosing a period for which periods and bank accounts you can request.

This asks for a PDF statement for the whole of May:

curl "https://api.griffin.com${ACCOUNT_STATEMENTS_URL}" \
  -X 'POST' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '
{
  "format": "griffin-pdf",
  "start-date": "2026-05-01",
  "end-date": "2026-05-31"
}'

In the sandbox, ask for "format": "xero-csv": we don't produce PDF statements for sandbox bank accounts.

We respond with 201 Created and the new statement, which is pending:

{
  "statement-url": "/v0/bank/statements/st.abc123",
  "account-url": "/v0/bank/accounts/ba.xyz789",
  "format": "griffin-pdf",
  "start-date": "2026-05-01",
  "end-date": "2026-05-31",
  "status": "pending",
  "created-at": "2026-06-24T10:30:00.000Z"
}

Store the statement-url. It's also in the response's Location header. You'll use it to check the statement in step 2.

caution

Requesting a statement isn't idempotent: if you send the same request twice, we create two statements. If you don't know whether a request succeeded, for example after a timeout or a 5xx response, list the account's statements before you retry.

Errors

If we can't accept a request, we respond with an error. Each error in the response's errors list has a code. A 422 response lists every reason the request failed, except an end-date before the start-date, which we report on its own.

Status	Code	Reason
400	–	The format, start-date or end-date is missing or invalid.
403	–	Your API key doesn't have the Manage accounts role.
404	–	The bank account doesn't exist.
422	period-inverted	The end-date is before the start-date.
422	period-unfinished	The end-date isn't before today in UK time.
422	too-many-transactions	The period has too many transactions for a griffin-pdf statement. Choose a shorter period.
422	branded-sandbox	You asked for a griffin-pdf statement for a sandbox bank account.

Don't retry a 400, 403 or 422 unchanged: fix the cause first.

Step 2: Wait for the document

Fetch the statement-url to see the statement's status:

curl "https://api.griffin.com${STATEMENT_URL}" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

Status	Description
pending	We're generating the statement's document.
generated	The document is ready to download.
failed	We couldn't generate the document.

Keep checking until the status is generated or failed. Neither of these changes again. Most statements are ready within a few seconds, but some can take several minutes. Check every few seconds at first, and leave longer gaps between checks if the statement is still pending.

Once the statement is generated, it has a statement-download-url:

{
  "statement-url": "/v0/bank/statements/st.abc123",
  "account-url": "/v0/bank/accounts/ba.xyz789",
  "format": "griffin-pdf",
  "start-date": "2026-05-01",
  "end-date": "2026-05-31",
  "status": "generated",
  "created-at": "2026-06-24T10:30:00.000Z",
  "statement-download-url": "/v0/bank/statements/st.abc123/download"
}

If a statement fails, contact support@griffin.com with its statement-url and we'll look into it.

Step 3: Download the document

Send a GET to the statement-download-url, with your API key:

curl "https://api.griffin.com${STATEMENT_DOWNLOAD_URL}" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  -OJ

We send the document with its content type (application/pdf or text/csv) and a filename such as statement_2026-05-01_to_2026-05-31_{id}.pdf. The -OJ option tells curl to save the file under that name.

The download URL only works with your API key, so you can't give it straight to your customers. To share a statement with a customer, download it to your own systems first and serve it from there.

If you try to download a statement that isn't generated, we respond with 404 Not Found. The error code is statement-not-generated for a pending statement, and statement-failed for a failed one.

Finding an account's statements

To list a bank account's statements, send a GET to its account-statements-url. This is useful when you want to show customers their past statements, or check what you've already requested before you retry.

curl "https://api.griffin.com${ACCOUNT_STATEMENTS_URL}" \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

{
  "statements": [
    {
      "statement-url": "/v0/bank/statements/st.abc123",
      "account-url": "/v0/bank/accounts/ba.xyz789",
      "format": "griffin-pdf",
      "start-date": "2026-05-01",
      "end-date": "2026-05-31",
      "status": "generated",
      "created-at": "2026-06-24T10:30:00.000Z",
      "statement-download-url": "/v0/bank/statements/st.abc123/download"
    }
  ],
  "links": {
    "prev": null,
    "next": null
  }
}

We list the most recently requested statements first, a page at a time. To get the next page, follow links.next. You can change the order and the page size with these query parameters:

Parameter	Description
sort	-created-at for newest first (the default), or created-at for oldest first.
page[size]	How many statements to return in each page, from 1 to 200. The default is 25.
page[after] / page[before]	Cursors for paging. Take them from the links in a response, rather than building them.

In the Griffin app

Your team can also download statements in the Griffin app, including the ones you requested through the API:

1. Go to the bank account in the Griffin app.
2. Open the Statements tab. Each row shows a statement's period, format, when it was requested and its status.
3. When a statement's status is Generated, click Download.