List Statements

GET /api/v1/statements

Returns a paginated list of statements.

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	100	Items per page (max 500)
fields	string	all	Comma-separated field names
is_archived	boolean	-	Filter by archived status
account	string	-	Filter by account ID
step	string	-	Filter by processing step
file_type	string	-	Filter by file type (csv, pdf, xlsx)
parser_type	string	-	Filter by parser type
period_from	string	-	Filter statements overlapping on/after this date (YYYY-MM-DD)
period_to	string	-	Filter statements overlapping on/before this date (YYYY-MM-DD)
period_source	string	-	Filter by period source (extracted, computed, user_entered)
period_missing	boolean	-	Filter statements with missing period data
upload_from	string	-	Filter by upload date on/after this date (YYYY-MM-DD, on `created_at`)
upload_to	string	-	Filter by upload date on/before this date (YYYY-MM-DD, on `created_at`)
reviewed	boolean	-	Filter by review status. `false` includes never-reviewed statements
sort_by	string	created_at	Sort column: `created_at`, `period_start`, `period_end`, `file_size`
sort_order	string	DESC	Sort direction: `ASC` or `DESC`

Example Request

curl -X GET "https://statements.finopsbricks.com/api/v1/statements" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Example: List Statements for Account

curl -X GET "https://statements.finopsbricks.com/api/v1/statements?account=acc123&is_archived=false" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Example: Find Failed Statements

curl -X GET "https://statements.finopsbricks.com/api/v1/statements?step=uploaded" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

This returns statements that haven't progressed past the initial upload step, which may indicate processing issues.

Example: Filter by File Type

curl -X GET "https://statements.finopsbricks.com/api/v1/statements?file_type=pdf" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Example: Filter by Statement Period

Find all statements that cover December 2024:

curl -X GET "https://statements.finopsbricks.com/api/v1/statements?period_from=2024-12-01&period_to=2024-12-31" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

This uses overlap logic: a statement is included if its period intersects with the query range.

Example: Find Statements with Missing Period

curl -X GET "https://statements.finopsbricks.com/api/v1/statements?period_missing=true" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Example: Unreviewed Statements Uploaded This Month

reviewed=false includes statements that have never been reviewed:

curl -X GET "https://statements.finopsbricks.com/api/v1/statements?reviewed=false&upload_from=2025-01-01" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Example: Sort by Largest File

curl -X GET "https://statements.finopsbricks.com/api/v1/statements?sort_by=file_size&sort_order=DESC" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": "stmt123xyz",
      "file_name": "statement_jan_2025.pdf",
      "mime_type": "application/pdf",
      "file_type": "pdf",
      "file_size": "245760",
      "parser_type": "hdfc_savings__pdf",
      "step": "complete",
      "error": null,
      "account_id": "acc123",
      "account_name": "Main Account",
      "account_currency": "INR",
      "is_archived": false,
      "created_at": "2025-01-05T10:30:00.000Z",
      "period_start": "2025-01-01",
      "period_end": "2025-01-31",
      "opening_balance": 5000050,
      "closing_balance": 4825075,
      "data_source": {
        "period_start": "extracted",
        "period_end": "extracted",
        "opening_balance": "computed",
        "closing_balance": "computed"
      },
      "review": {
        "is_done": true,
        "at": "2025-01-06T14:30:00.000Z",
        "type": "human",
        "by": "user123",
        "work_record_id": "wr456"
      }
    }
  ],
  "page_context": {
    "count": 1,
    "page": 1,
    "per_page": 100,
    "total": 25,
    "has_more": false
  }
}

Response Fields

See Statement Object for field descriptions.

Errors

Code	Description
401	Invalid or missing API credentials
403	API key lacks `statements:read` permission