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. Each item has report_name, title, description, input_type (which tells you which request fields it needs) and requires_cfo_suite. Commonly used report_name values:

These report_name values require the CFO Suite add-on and return 403 without it: profit_and_loss_comparative, income_statement_periodic, income_statement_details, pnl_by_customer, pnl_by_department, balance_sheet_comparative, balance_sheet_monthly, cash_flow_periodic, cash_flow_forecast, financial_ratios, financial_summary_dashboard, budget_vs_actual, working_capital, retained_earnings, shareholder_loans, report_1099 and subscription_costs. An unknown report_name is a 400.

Generate a Report

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"
  }'

The response is 202 Accepted:

{
  "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 with Temporal",
    "executor": "temporal"
  }
}

status is queued, or in_progress if an identical report is already being generated (the request is de-duplicated rather than run twice). The task_id is deterministic for the same report name, period and parameters.

Retrieve the Finished Report

Either poll the task with GET /api/v1/tasks/task/{task_id} (the response status becomes SUCCESS and result carries the s3_key and a download_link; an unknown task returns HTTP 200 with status: NOT_FOUND), or poll the report list — the newest reports come first — until one with your report_name and period appears:

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, with dates resolved, so you can match it), s3_key, created_at, downloaded_at, generated_by_name and a download_url. GET /api/v1/reports/{report_id} fetches one by ID. Add client_visible_only=true to the list to see only reports shared with clients.

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:

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 and its file.

To preview a stored PDF, Excel or PowerPoint file as images, GET /api/v1/reports/preview-info?s3_key=… returns available and page_count (up to 20 pages), and GET /api/v1/reports/preview-page?s3_key=…&page=1 returns that page as a PNG.

Related

• GET /api/v1/reports/subledger-gl-reconciliation — checks that the AR/AP sub-ledgers agree with the general ledger control accounts. Takes as_of_date (YYYY-MM-DD, default today) and parent_ledger_id (reconcile only that control account and its sub-ledgers; a liability account is read as the payables side). The ar and ap sections hold the totals in cents (open documents minus GL balance) and rows, largest difference first, hold one entry per customer (AR) or vendor (AP), plus one for lines that cannot be attributed to anyone. Each row has kind, customer_or_vendor, party_id (null when unattributed), subledger_balance_cents (the party's GL balance), open_documents_cents, difference_cents (GL balance minus open documents, the opposite sign to the section totals) and explanations: tagged causes (fee_shortfall, unapplied_credit, unposted_payment, rounding), each with an amount and whether it accounts for the difference. A manual journal entry posted straight to AR or AP carries no tag and shows as an unexplained difference. As-of figures are approximate for documents voided or written off after the date, because statuses are not historized. The MCP tool is get_subledger_gl_reconciliation.
• 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. import-templates.zip bundles them all; import-templates/{template_key}.csv and .md fetch one template or its README.