Download a filing report · Ownrecord docs

Returns the report file of a prepared period in csv or xlsx (spec §21.2): its name, type, size and SHA-256, and for CSV its content. The CSV is one table: a section column (summary, then the report's sections, e.g. supplies, corrections, balances, amounts_by_currency and reconciliation for an EU OSS return, ec_sales_list for an EU domestic one, boxes for a UK one, sales_by_state for a US one) followed by the sections' columns; money as decimals in the row's currency (or the report's), rates as percentages. In the console, both files download from the period's page.

At a glance

REST: GET /api/v1/filing_periods/{id}/report/{format}
MCP tool: filing_periods_report
Operation ID: filing_periods.report
Scope: Legal entity
Permission: filings:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the filings:read scope
Since: M8

Request

Path parameters

Field	Type	Description
`id`	`fp_…` ID	The filing period (`fp_…`).
`format`	one of `csv`, `xlsx`	`csv` or `xlsx`.

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

Field	Type	Description
`format`	one of `csv`, `xlsx`, `xml`
`fileId`	`file_…` ID
`filename`	string
`contentType`	string
`size`	integer
`sha256`	string
`object`	`"filing_report_file"`
`filingPeriodId`	`fp_…` ID
`content`	string or null

Examples

The CSV of the Q3 OSS return

HTTP

GET /api/v1/filing_periods/fp_01m4tx5nj8emwbyf7y9vcf47y0/report/csv
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "filing_report_file",
  "filingPeriodId": "fp_01m4tx5nj8emwbyf7y9vcf47y0",
  "format": "csv",
  "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y2",
  "filename": "EU_OSS_UNION-2026-Q3.csv",
  "contentType": "text/csv; charset=utf-8",
  "size": 2381,
  "sha256": "5d1c9d6b7f3e0a4c8b2f1e6d9a7c3b5e0f4d8a2c6b1e9f7d3a5c0b8e2f6d4a1c",
  "content": "section,item,label,value,currency,member_state,rate,…\r\nsummary,report,Report,eu_oss,,,,…\r\n…"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A field is malformed (`param` names it).	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	No filing period with this ID exists for this legal entity and mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`scope_required`	400	The request names no legal entity (an org key without `Ownrecord-Entity`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`filing_report_not_ready`	409	The period has no report in that format yet: prepare it first.	Prepare the period first (`filing_periods.prepare`), then download its report.
`permission_denied`	403	You can't see this entity's filings.	Ask an organization owner or admin for a role or scope that allows this action.
`entitlement_required`	403	A format other than CSV, on a plan with basic filing reports (`filing.reports`).	Upgrade the organization's plan, or remove something to get back under the limit.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

The CSV of the Q3 OSS return#

Errors#