# Get a filing period > The filing_periods.get operation: GET /api/v1/filing_periods/{id} in the REST API and the filing_periods_get tool in the MCP server. Returns one filing period: its dates, due date and status, the registration it files for, and once prepared the report (spec §21.2): its totals in the filing currency, its sections (for the EU One-Stop Shop: supplies per member state and rate, corrections of earlier periods, the balance per member state), the ECB rates it converted with, and the reconciliation with the ledger's tax payable per jurisdiction and currency. Money cells are micros and rates parts per million, as strings. `files` are the report's CSV and XLSX (`filing_periods.report`), `receipts` the submission's confirmation, `paymentLedgerTxnIds` the ledger postings of the payment. `actions` says which of lock, prepare, submit and mark paid the period allows now, and if not, why (the error code it would fail with). ## At a glance - **REST:** `GET /api/v1/filing_periods/{id}` - **MCP tool:** `filing_periods_get` - **Operation ID:** `filing_periods.get` - **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_…`). | ### Query parameters This operation takes no query parameters. ## Response `200 OK` with a JSON object: | Field | Type | Description | | -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ | | `id` | `fp_…` ID | | | `object` | `"filing_period"` | | | `entityId` | `ent_…` ID | | | `livemode` | boolean | | | `regimeId` | string | | | `registrationId` | `regn_…` ID | | | `reportKind` | one of `eu_oss`, `eu_domestic`, `uk_vat`, `ch_mwst`, `generic`, `us_state` | | | `reportAvailable` | boolean | | | `frequency` | one of `monthly`, `quarterly`, `annual` | | | `periodKey` | string | The period: "2026-Q3", "2026-07" or "2026". | | `periodStart` | date-time | | | `periodEnd` | date-time | The end (exclusive): the next period's first local midnight. | | `firstDay` | string | | | `lastDay` | string | | | `timeZone` | string | | | `currency` | string | | | `dueDate` | string | | | `dueAt` | date-time | 23:59:59 local time on the due date. | | `lockableAt` | date-time | | | `status` | one of `open`, `locked`, `prepared`, `submitted`, `paid` | | | `statusChangedAt` | date-time | | | `lockedAt` | date-time or null | | | `preparedAt` | date-time or null | | | `submittedAt` | date-time or null | | | `reference` | string or null | | | `paidAt` | date-time or null | | | `paymentRef` | string or null | | | `totals` | object or null | | | `createdAt` | date-time | | | `updatedAt` | date-time | | | `registration` | object or null | | | `endsBeforeRegistration` | boolean | | | `report` | object or null | | | `files` | array of object | | | `files[].format` | one of `csv`, `xlsx`, `xml` | | | `files[].fileId` | `file_…` ID | | | `files[].filename` | string | | | `files[].contentType` | string | | | `files[].size` | integer | | | `files[].sha256` | string | | | `receipts` | array of object | | | `receipts[].kind` | one of `file`, `reference` | | | `receipts[].reference` | string | | | `receipts[].label` | string or null | | | `receipts[].addedAt` | date-time | | | `receipts[].addedBy` | string | | | `paymentLedgerTxnIds` | array of `txn_…` ID | | | `reminders` | array of object | | | `reminders[].code` | string | | | `reminders[].at` | date-time | | | `reminders[].skipped` | boolean | | | `history` | array of object | | | `history[].from` | one of `open`, `locked`, `prepared`, `submitted`, `paid` or null | | | `history[].to` | one of `open`, `locked`, `prepared`, `submitted`, `paid` | | | `history[].at` | date-time | | | `history[].by` | string | | | `history[].note` | string or null | | | `actions` | object | | | `actions.lock` | object | | | `actions.lock.allowed` | boolean | | | `actions.lock.code` | string or null | | | `actions.lock.message` | string or null | | | `actions.prepare` | object | | | `actions.prepare.allowed` | boolean | | | `actions.prepare.code` | string or null | | | `actions.prepare.message` | string or null | | | `actions.submit` | object | | | `actions.submit.allowed` | boolean | | | `actions.submit.code` | string or null | | | `actions.submit.message` | string or null | | | `actions.markPaid` | object | | | `actions.markPaid.allowed` | boolean | | | `actions.markPaid.code` | string or null | | | `actions.markPaid.message` | string or null | | ## Examples ### A prepared OSS return ```http GET /api/v1/filing_periods/fp_01m4tx5nj8emwbyf7y9vcf47y0 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "id": "fp_01m4tx5nj8emwbyf7y9vcf47y0", "object": "filing_period", "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "reportKind": "eu_oss", "reportAvailable": true, "frequency": "quarterly", "periodKey": "2026-Q3", "periodStart": "2026-06-30T22:00:00.000Z", "periodEnd": "2026-09-30T22:00:00.000Z", "firstDay": "2026-07-01", "lastDay": "2026-09-30", "timeZone": "Europe/Zagreb", "currency": "EUR", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z", "lockableAt": "2026-09-30T22:00:00.000Z", "status": "prepared", "statusChangedAt": "2026-10-02T08:05:00.000Z", "lockedAt": "2026-10-02T08:00:00.000Z", "preparedAt": "2026-10-02T08:05:00.000Z", "submittedAt": null, "reference": null, "paidAt": null, "paymentRef": null, "totals": { "currency": "EUR", "taxable": "1500000000", "tax": "290000000", "corrections": "-19000000", "due": "271000000", "refundable": "0" }, "createdAt": "2026-07-01T03:00:00.000Z", "updatedAt": "2026-10-02T08:05:00.000Z", "registration": { "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk", "state": "registered", "registrationNumber": "HR12345678901", "effectiveFrom": "2026-03-31T22:00:00.000Z" }, "endsBeforeRegistration": false, "report": { "kind": "eu_oss", "currency": "EUR", "rounding": "half_up", "fxRule": null, "generatedAt": "2026-10-02T08:05:00.000Z", "fx": [], "sections": [ { "id": "supplies", "title": "Supplies by member state of consumption and rate", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "rate", "label": "VAT rate", "type": "rate" }, { "key": "rateKind", "label": "Rate type", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "memberState": "DE", "rate": "190000", "rateKind": "standard", "taxable": "1000000000", "vat": "190000000", "lines": 8 }, { "memberState": "FR", "rate": "200000", "rateKind": "standard", "taxable": "500000000", "vat": "100000000", "lines": 3 } ] }, { "id": "corrections", "title": "Corrections of earlier periods", "columns": [ { "key": "originalPeriod", "label": "Period corrected", "type": "text" }, { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "taxable", "label": "Taxable amount", "type": "money" }, { "key": "vat", "label": "VAT", "type": "money" }, { "key": "lines", "label": "Lines", "type": "count" } ], "rows": [ { "originalPeriod": "2026-Q2", "memberState": "DE", "taxable": "-100000000", "vat": "-19000000", "lines": 1 } ] }, { "id": "balances", "title": "VAT due per member state", "columns": [ { "key": "memberState", "label": "Member state", "type": "text" }, { "key": "supplies", "label": "VAT on supplies", "type": "money" }, { "key": "corrections", "label": "Corrections", "type": "money" }, { "key": "balance", "label": "Balance", "type": "money" } ], "rows": [ { "memberState": "DE", "supplies": "190000000", "corrections": "-19000000", "balance": "171000000" }, { "memberState": "FR", "supplies": "100000000", "corrections": "0", "balance": "100000000" } ] }, { "id": "reconciliation", "title": "Reconciliation with the ledger", "columns": [ { "key": "jurisdiction", "label": "Jurisdiction", "type": "text" }, { "key": "currency", "label": "Currency", "type": "text" }, { "key": "reportTax", "label": "Report tax", "type": "money" }, { "key": "ledgerTax", "label": "Ledger tax payable", "type": "money" }, { "key": "difference", "label": "Difference", "type": "money" } ], "rows": [ { "jurisdiction": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdiction": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] } ], "reconciliation": { "matches": true, "rows": [ { "jurisdictionId": "DE", "currency": "EUR", "reportTax": "171000000", "ledgerTax": "171000000", "difference": "0" }, { "jurisdictionId": "FR", "currency": "EUR", "reportTax": "100000000", "ledgerTax": "100000000", "difference": "0" } ] }, "counts": { "lines": 12, "corrections": 1, "notReported": 0, "documents": 12 } }, "files": [ { "format": "csv", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y2", "filename": "EU_OSS_UNION-2026-Q3.csv", "contentType": "text/csv; charset=utf-8", "size": 2381, "sha256": "5d1c9d6b7f3e0a4c8b2f1e6d9a7c3b5e0f4d8a2c6b1e9f7d3a5c0b8e2f6d4a1c" }, { "format": "xlsx", "fileId": "file_01m4tx5nj8emwbyf7y9vcf47y3", "filename": "EU_OSS_UNION-2026-Q3.xlsx", "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "size": 9184, "sha256": "8a3f6c1e9d4b7a2f5c0e8d3b6a1f4c9e7d2b5a0f3c8e6d1b4a9f7c2e5d0b3a6f" } ], "receipts": [], "paymentLedgerTxnIds": [], "reminders": [], "history": [ { "from": null, "to": "open", "at": "2026-07-01T03:00:00.000Z", "by": "system", "note": null }, { "from": "open", "to": "locked", "at": "2026-10-02T08:00:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null }, { "from": "locked", "to": "prepared", "at": "2026-10-02T08:05:00.000Z", "by": "usr_01m4tx5nj8emwbyf7y9vcf47xa", "note": null } ], "actions": { "lock": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is prepared: \"lock\" needs open." }, "prepare": { "allowed": true, "code": null, "message": null }, "submit": { "allowed": true, "code": null, "message": null }, "markPaid": { "allowed": false, "code": "filing_period_status_invalid", "message": "This period is prepared: \"mark_paid\" needs submitted." } } } ``` ## Errors | Code | HTTP status | When | What to do | | ---------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`). | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#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. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).