# Reports

> Generate financial reports as Excel, CSV, PDF or HTML files with download URLs.

- **Category:** Guides
- HTML version: https://www.ondayzero.com/docs/guides/reports
- All guides: https://www.ondayzero.com/docs/guides/index.md
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

# Reports

Generate financial reports as files (Excel by default; CSV, PDF or HTML on request). Generation runs in the background; finished reports are stored and downloadable through the API.

## Available Reports

`GET /api/v1/reports/types` returns the full, current list with each report's `input_type`, which tells you which request fields it needs. Commonly used `report_name` values:

| `report_name` | Description | Inputs |
|---------------|-------------|--------|
| `master_transactions` | All transactions across accounts | `start_date`, `end_date` |
| `journal_entry_report` / `audit_trail` | Journal entries and change history | `start_date`, `end_date` |
| `trial_balance` | Debits/credits verification | `start_date`, `end_date` |
| `general_ledger` | Transactions per account (optionally one `ledger_id`) | `start_date`, `end_date` |
| `profit_and_loss` | Income statement | `start_date`, `end_date` |
| `profit_and_loss_comparative` | P&L vs. a comparison period | dates + `comparison_*` fields |
| `pnl_by_customer` / `pnl_by_department` | P&L segmented by customer or tag | dates + `additional_params.customer_id` / `tag_group_id`, `tag_ids` |
| `balance_sheet` | Assets, liabilities, equity as of a date | `end_date` |
| `balance_sheet_comparative` / `balance_sheet_monthly` | Comparative / month-by-month balance sheets | `end_date` + comparison, or a date range |
| `cash_flow_statement` / `cash_flow_forecast` | Cash flow, historical or projected | `start_date`, `end_date` / forecast params |
| `ar_report` / `ap_report` | Invoice and bill summaries with aging | none |
| `unpaid_ar_as_of` / `unpaid_ap_as_of` | Open receivables / payables at a date | `end_date` |
| `customer_statements` / `vendor_statements` | Statements per customer or vendor | dates + `additional_params.customer_id` / `vendor_id` |
| `tax_summary`, `report_1099`, `check_register`, `bank_reconciliation` | Compliance and banking | `start_date`, `end_date` |
| `budget_vs_actual`, `expense_by_category`, `sales_report`, `cogs_report`, `fixed_assets_depreciation`, `inventory_by_location`, `products_report` | Operational reports | mostly `start_date`, `end_date` |
| `financial_ratios`, `working_capital`, `saas_metrics`, `quality_of_earnings`, `deferred_revenue_waterfall` | CFO analytics | dates / `end_date` |

Advanced reports (comparative, periodic, ratios, forecasting, compliance) require the **CFO Suite** add-on and return `403` without it.

## Generate a Report

```bash
curl -X POST "https://api.ondayzero.com/api/v1/reports" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "report_name": "profit_and_loss",
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "output_format": "pdf"
  }'
```

| Field | Description |
|-------|-------------|
| `report_name` | Required. One of the names from `/reports/types` |
| `period_type` | `custom` (default — use `start_date`/`end_date`), `tax_year` or `tax_quarter` (use `tax_year` and `tax_quarter`; dates are derived from the business's fiscal year end) |
| `start_date` / `end_date` | `YYYY-MM-DD`. Point-in-time reports need only `end_date` |
| `output_format` | `xlsx` (default), `csv`, `html`, `pdf` |
| `comparison_period_type`, `comparison_start_date` / `comparison_end_date`, `comparison_tax_year` / `comparison_tax_quarter` | Prior period for `*_comparative` reports |
| `ledger_id`, `tag_group_id`, `tag_ids` | Narrow `general_ledger` to one account, or segment `pnl_by_department` |
| `additional_params` | Report-specific options, e.g. `{"customer_id": "…"}` for `customer_statements` |
| `file_s3_key` / `s3_keys` | Input files for upload-driven reports (see [File Uploads](/docs/guides/uploads)) |

The response is `202 Accepted`:

```json
{
  "success": true,
  "data": {
    "task_id": "report-generation-…-profit_and_loss-start-2026-01-01-end-2026-03-31",
    "status": "queued",
    "report_name": "profit_and_loss",
    "business_id": "…",
    "message": "Report generation queued successfully"
  }
}
```

`status` is `queued`, or `in_progress` if an identical report is already being generated (the request is de-duplicated rather than run twice).

## Retrieve the Finished Report

Poll the report list — the newest reports come first — until one with your `report_name` and period appears:

```bash
curl "https://api.ondayzero.com/api/v1/reports?limit=5" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

Each report has `id`, `report_name`, `generation_params` (the request you sent, so you can match it), `s3_key`, `created_at` and a `download_url`. `GET /api/v1/reports/{report_id}` fetches one by ID.

## Download

`download_url` points at `GET /api/v1/reports/download?s3_key=…` — a same-origin endpoint that validates ownership, records the download, and then `307`-redirects to a short-lived presigned S3 URL (falling back to streaming the file itself). Send the usual `Authorization` and `x-business-id` headers and follow redirects:

```bash
curl -L -o pnl-q1.pdf "https://api.ondayzero.com/api/v1/reports/download?s3_key=reports/YOUR_BUSINESS_ID/profit_and_loss_2026-01-01_2026-03-31.pdf" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

Add `inline=true` to get a `Content-Disposition: inline` response for viewing in a browser, or `filename=…` to rename the download. `DELETE /api/v1/reports/{report_id}` removes a stored report.

## Related

- `GET /api/v1/reports/subledger-gl-reconciliation` — checks that the AR/AP sub-ledgers agree with the general ledger control accounts.
- `POST /api/v1/reports/suggest` — AI suggestions for which reports are worth running given recent activity.
- `GET /api/v1/reports/import-templates` — CSV templates (and READMEs) for bulk imports of transactions, journal entries and more.