MCP
Create export
Asynchronously export an income statement, balance sheet, or cash flow as PDF, CSV, or XLSX. Requires API access: Manage and Reports: View. Does not edit company books; read-only OAuth connections may request exports. Internal read-only keys cannot POST. All report types require start_date and end_date. Balance sheet exports compare cumulative balances across periods in that range; start_date selects displayed periods, not an opening cutoff for historical balances. A single date field is not accepted by the export endpoint. Ranges may cover at most 120 calendar months, counting both boundary months, regardless of grouping or format. Longer ranges return 400 invalid_date_range before creating or queuing a job. PDF exports additionally support at most 13 displayed periods, using the company’s calendar/fiscal report settings. Larger PDFs return 400 invalid_date_range with param end_date; use a shorter range, coarser grouping, CSV, or XLSX instead. group_by is an object: period controls time columns (month, quarter, or year; default month), and rows controls row grouping (category or department; default category). Department rows are supported only for income statements, export the GAAP department statement, and require that feature. Omitted group_by or either member uses the corresponding default. Company, actor, reporting-date settings, and filename are inferred by Finta. Period columns follow the company’s existing calendar/fiscal report settings; this endpoint accepts no date_type. The worker reads the books when it generates the file, not from a frozen snapshot at submission. Completed files are retained results; use a new Idempotency-Key for a new export of updated books. Email delivery is not supported. Export records and their files are retained; there is no automatic age-based cleanup for exports in the application. Reports::GenerationRequestWorker runs on the existing critical queue. A company may have at most five unfinished API exports across all submitting users. Additional new exports return 429 report_export_limit_exceeded without creating or enqueueing a job. Existing-key replays and retrieval remain available. A completed or failed export releases its slot; retry rejected submissions after an export finishes.
Idempotency-Key is required and scoped to company, submitting user, and this operation. Identical normalized inputs return the existing export with its current status; changed inputs return 409 idempotency_key_conflict. The key remains reserved for the lifetime of the export. A pending replay without a recorded enqueue repairs an interrupted dispatch; worker executions are serialized and completed exports are not generated again. A failed export requires a new key to retry. Creation and replay return 201 with Location pointing to the retrieval endpoint. If enqueue acknowledgement or bookkeeping fails, creation returns 503 and retains a pending export. Retry with the same key to recover; a job may already be queued, and duplicate deliveries are serialized. These failures do not consume the key with a terminal enqueue failure. The file is generated in the background; poll Location with backoff until succeeded or failed. Every poll counts toward the usual API limits. No webhook or MCP event subscription is created.
Authorizations
API key prefixed with finta_
Headers
Nonblank, case-sensitive key; reuse with identical inputs after an uncertain response.
1 - 255Body
income_statement exports profit and loss; balance_sheet compares cumulative balances across the requested periods; cash_flow exports operating, investing, and financing activity. GAAP P&L uses income_statement with department rows.
income_statement, balance_sheet, cash_flow Required for all report types. For balance sheets, selects the first displayed period while retaining cumulative historical balances.
Inclusive; required for all report types. Must be on or after start_date. The range may cover at most 120 calendar months, counting both boundary months. PDF exports additionally allow at most 13 displayed periods.
pdf, csv, xlsx Omitted members default to month for period and category for rows. Department rows are supported only for income statements and require the feature.
Response
Export created or replayed; status may already be terminal on replay.
^export_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$report_export income_statement, balance_sheet, cash_flow pdf, csv, xlsx Omitted members default to month for period and category for rows. Department rows are supported only for income statements and require the feature.
pending awaits generation; processing includes generation and retry waits; succeeded exposes the retained file after final access checks while within 30 days of completed_at, then file is null; failed is terminal and requires a new key for a new job. An HTTP 200 retrieval may still carry failed status.
pending, processing, succeeded, failed Unix timestamp of the first generation attempt. Null until generation starts, including a terminal failure when access is revoked before generation.
Unix timestamp of terminal completion, whether succeeded or failed. Null while unfinished.
Cumulative generation attempt duration in milliseconds, including upload but excluding queue and retry wait time. Null until an attempt finishes.
x >= 0Available only for succeeded exports before completed_at plus 30 days. Null at or after that cutoff, including on idempotent POST replay; status remains succeeded and error remains null. Within the window, refresh download_url by retrieving the export again. Already-issued links keep their original expiry; neither link expiry nor the regeneration cutoff removes the stored file.
Safe job failure details, present only when status is failed. This is distinct from an HTTP error envelope. New submissions with unconfirmed dispatch return HTTP 503 and retain a pending job, rather than setting enqueue_failed.