Filing calendar · Ownrecord docs

The filing calendar (spec §21.3): filing periods of every legal entity of the organization, or of one entity (an entity key, or entity_id), in the mode of the request, earliest due date first. By default only the periods not paid yet (open, locked, prepared, submitted); filter by status, by due date with dueFrom and dueTo, and cap with limit (default 100).

Each item is the period with its entity's name and slug, the whole days until it is due (daysUntilDue, negative once past) and overdue (past the due instant and not yet submitted). Ownrecord also reminds the entity's tax managers and finance team 14, 7 and 2 days before each due date (alerts FILING_DUE_14, FILING_DUE_7, FILING_DUE_2).

At a glance

REST: GET /api/v1/filing_calendar
MCP tool: filing_periods_calendar
Operation ID: filing_periods.calendar
Scope: Organization, or one of its legal entities or brands
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

Query parameters

Field	Type	Required	Description
`status`	one of `open`, `locked`, `prepared`, `submitted`, `paid` or array of one of `open`, `locked`, `prepared`, `submitted`, `paid`	No	Only periods in these statuses. Default: every period not paid yet.
`dueFrom`	string	No	Due on or after this date (UTC), `YYYY-MM-DD`.
`dueTo`	string	No	Due on or before this date (UTC), `YYYY-MM-DD`.
`limit`	integer (1 to 500)	No	At most this many periods, 1 to 500 (default 100).

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].id`	`fp_…` ID
`data[].object`	`"filing_period"`
`data[].entityId`	`ent_…` ID
`data[].livemode`	boolean
`data[].regimeId`	string
`data[].registrationId`	`regn_…` ID
`data[].reportKind`	one of `eu_oss`, `eu_domestic`, `uk_vat`, `ch_mwst`, `generic`, `us_state`
`data[].reportAvailable`	boolean
`data[].frequency`	one of `monthly`, `quarterly`, `annual`
`data[].periodKey`	string	The period: "2026-Q3", "2026-07" or "2026".
`data[].periodStart`	date-time
`data[].periodEnd`	date-time	The end (exclusive): the next period's first local midnight.
`data[].firstDay`	string
`data[].lastDay`	string
`data[].timeZone`	string
`data[].currency`	string
`data[].dueDate`	string
`data[].dueAt`	date-time	23:59:59 local time on the due date.
`data[].lockableAt`	date-time
`data[].status`	one of `open`, `locked`, `prepared`, `submitted`, `paid`
`data[].statusChangedAt`	date-time
`data[].lockedAt`	date-time or null
`data[].preparedAt`	date-time or null
`data[].submittedAt`	date-time or null
`data[].reference`	string or null
`data[].paidAt`	date-time or null
`data[].paymentRef`	string or null
`data[].totals`	object or null
`data[].createdAt`	date-time
`data[].updatedAt`	date-time
`data[].entityName`	string
`data[].entitySlug`	string
`data[].daysUntilDue`	integer
`data[].overdue`	boolean

Examples

What is due next across the organization

HTTP

GET /api/v1/filing_calendar
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "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": "open",
      "statusChangedAt": "2026-07-01T03:00:00.000Z",
      "lockedAt": null,
      "preparedAt": null,
      "submittedAt": null,
      "reference": null,
      "paidAt": null,
      "paymentRef": null,
      "totals": null,
      "createdAt": "2026-07-01T03:00:00.000Z",
      "updatedAt": "2026-07-01T03:00:00.000Z",
      "entityName": "Acme Digital d.o.o.",
      "entitySlug": "acme-hr",
      "daysUntilDue": 11,
      "overdue": false
    },
    {
      "id": "fp_01m4tx5nj8emwbyf7y9vcf47y1",
      "object": "filing_period",
      "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
      "livemode": true,
      "regimeId": "HR_DOMESTIC",
      "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk",
      "reportKind": "eu_domestic",
      "reportAvailable": true,
      "frequency": "monthly",
      "periodKey": "2026-10",
      "periodStart": "2026-09-30T22:00:00.000Z",
      "periodEnd": "2026-10-31T23:00:00.000Z",
      "firstDay": "2026-10-01",
      "lastDay": "2026-10-31",
      "timeZone": "Europe/Zagreb",
      "currency": "EUR",
      "dueDate": "2026-11-20",
      "dueAt": "2026-11-20T22:59:59.000Z",
      "lockableAt": "2026-10-31T23:00:00.000Z",
      "status": "open",
      "statusChangedAt": "2026-07-01T03:00:00.000Z",
      "lockedAt": null,
      "preparedAt": null,
      "submittedAt": null,
      "reference": null,
      "paidAt": null,
      "paymentRef": null,
      "totals": null,
      "createdAt": "2026-07-01T03:00:00.000Z",
      "updatedAt": "2026-07-01T03:00:00.000Z",
      "entityName": "Acme Digital d.o.o.",
      "entitySlug": "acme-hr",
      "daysUntilDue": 31,
      "overdue": false
    }
  ]
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A filter is malformed (`param` names it).	Fix the fields listed in `details.issues` and send the request again.
`permission_denied`	403	You can't see filings here.	Ask an organization owner or admin for a role or scope that allows this action.

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

At a glance#

Request#

Query parameters#

Response#

Examples#

What is due next across the organization#

Errors#