Generate report

POST /api/v1/reports

Queue a report for generation and return task ID for tracking.

Operation ID: generate_report_api_v1_reports_post · View as markdown · OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: ReportCreateRequest

report_name string required: Report type identifier. Must match a supported report_name from the /reports endpoint. Examples: 'master_transactions', 'trial_balance', 'general_ledger', 'profit_and_loss_comparative', 'ar_report', 'cogs_report', 'shareholder_loans'. See GET /reports for the complete list of available report types.
period_type ReportPeriodType: Controls how report dates are determined. 'custom' (default): Use start_date/end_date fields directly. 'tax_year': Calculate full fiscal year dates from business's tax_year_end_month config. 'tax_quarter': Calculate quarter dates within a fiscal year. When using tax_year or tax_quarter, the resolved dates will be stored in generation_params.
tax_year integer: The tax/fiscal year for period calculation. Required when period_type is 'tax_year' or 'tax_quarter'. Example: 2026. The actual date range depends on the business's tax_year_end_month setting. For a business with tax year ending March 31, tax_year=2026 covers April 1, 2025 through March 31, 2026.
tax_quarter integer: The quarter within the tax year (1-4). Required when period_type is 'tax_quarter'. Q1 is the FIRST quarter of the fiscal year, which may start in the prior calendar year for non-calendar fiscal years. Example: For a March fiscal year-end, Q1 of tax_year=2026 covers April 1-June 30, 2025.
start_date string: Report period start date in YYYY-MM-DD format (e.g., '2026-01-01'). Required when period_type='custom' for reports with input_type='date_start_end' or similar. Ignored when period_type is 'tax_year' or 'tax_quarter' (dates calculated automatically).
end_date string: Report period end date in YYYY-MM-DD format (e.g., '2026-12-31'). Required when period_type='custom' for date-range reports. For point-in-time reports (input_type='date_end_only'), only end_date is needed. Ignored when period_type is 'tax_year' or 'tax_quarter'.
comparison_period_type ReportPeriodType: Period type for the comparison/prior period in comparative reports. Same options as period_type: 'custom', 'tax_year', or 'tax_quarter'. Used with reports like 'profit_and_loss_comparative' and 'balance_sheet_comparative' to enable variance analysis between two periods.
comparison_tax_year integer: Tax year for the comparison period. Used when comparison_period_type is 'tax_year' or 'tax_quarter'. Example: Set to 2025 to compare against the current period's 2026 for year-over-year analysis.
comparison_tax_quarter integer: Quarter (1-4) for the comparison period. Required when comparison_period_type is 'tax_quarter'. Example: comparison_tax_quarter=1 with comparison_tax_year=2025 compares Q1 2025 against the current period.
comparison_start_date string: Start date for comparison period in YYYY-MM-DD format. Used when comparison_period_type='custom' for comparative reports. Example: '2025-01-01' to compare against prior year.
comparison_end_date string: End date for comparison period in YYYY-MM-DD format. Used when comparison_period_type='custom' for comparative reports. Example: '2025-12-31' to compare full prior year.
ledger_id string: UUID of a specific ledger account to filter the report. Currently used with 'general_ledger' report to show transactions for only one account instead of all accounts. When omitted, the general_ledger report includes all accounts. Example: '019ab37c-ledg-7000-8000-000000000001'.
instance_id string: Teal integration instance ID. Optional - if not specified, uses the business's default Teal instance. Only needed for businesses with multiple Teal instances or when overriding the default. Used for reports that fetch data from Teal (P&L, Balance Sheet).
file_s3_key string: S3 object key for file-based report inputs. Required for reports with input_type='file_upload' (e.g., 'cogs_report'). The file should be uploaded first via the upload endpoint. Example: 'uploads/business-123/cogs-data-2026.csv'.
s3_keys array · string: Array of S3 object keys when a report requires multiple input files. Each key should reference a previously uploaded file. Example: ['uploads/business-123/sales-q1.csv', 'uploads/business-123/sales-q2.csv'].
tag_group_id string: UUID of a specific tag group to filter the report. Used with 'pnl_by_department' to segment by tags within this group.
tag_ids array · string: List of specific tag UUIDs to filter the report. When multiple tags are provided for 'pnl_by_department', it generates a multi-sheet report with one P&L statement per tag.
additional_params object: Report-specific parameters that vary by report type. Supported parameters: customer_id (UUID): Filter customer_statements or pnl_by_customer to a specific customer. vendor_id (UUID): Filter vendor_statements to a specific vendor. include_zero_balances (bool): Include zero-balance accounts in trial_balance report. tag_group_id (UUID): Filter pnl_by_department to tags in a specific tag group. forecast_days (int): Number of days to forecast in cash_flow_forecast (default: 90). raw (bool): For general_ledger only — return a single flat sheet with no formatting or headers (default: false). Example: {'customer_id': '019abc-uuid', 'include_zero_balances': true}.
output_format ReportOutputFormat ReportOutputFormat: Output file format for the report. 'xlsx' (default): Excel format with formatting, multiple tabs, headers, and currency formatting. 'csv': Comma-separated values format as a single flat file without formatting. CSV is useful for importing into other systems or programmatic analysis.

Responses

202 Successful Response

Schema: ReportTaskResponse

task_id string required: Unique identifier for the report generation task. Use this to poll for status via GET /reports/task/{task_id}. Also serves as the Temporal workflow ID. Format: 'report-generation-{business_id}-{report_name}-{date_params}'. Example: 'report-generation-bus123-profit_and_loss-start-2026-01-01-end-2026-12-31'.
status string required: Initial status of the task. Typically 'queued' for new requests or 'in_progress' if a duplicate request was made while an identical report is already being generated. Values: 'queued', 'in_progress', 'failed'.
message string: Human-readable message about the task status. Provides context such as 'Report generation queued successfully with Temporal' or error details if the request failed validation.
business_id string required: UUID of the business for which the report is being generated. Echoed from the request for confirmation.
report_name string required: Type of report being generated. Echoed from the request for confirmation. Example: 'profit_and_loss', 'master_transactions', 'cogs_report'.

400 Bad Request - Invalid input

401 Unauthorized - Authentication required

403 Forbidden - Insufficient permissions

422 Validation Error

Schema: HTTPValidationError

detail array · ValidationError ValidationError

5 fields

loc array · string | integer required
msg string required
type string required
input object
ctx object

Code samples

POST /api/v1/reports

bash

curl -X POST 'https://api.ondayzero.com/api/v1/reports' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "report_name": "string"
}'

javascript

const response = await fetch('https://api.ondayzero.com/api/v1/reports', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "report_name": "string"
}),
});
const data = await response.json();

python

import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {
  "report_name": "string"
}

response = httpx.post("https://api.ondayzero.com/api/v1/reports", headers=headers, json=payload)
data = response.json()