List filing schedules · Ownrecord docs

The filing schedule of each of the entity's registrations that files returns (registered, in a grace period or deregistered), or that has periods or a schedule of its own, in the mode of the request (spec §21.1).

A schedule is the regime's filing spec (frequency and due rule, from the knowledge base) unless an operator set one on the registration with filing_periods.set_schedule (the frequency and stagger the tax authority assigned, and a due rule where the spec's can't be computed). problem says why no periods can be generated (due_other, frequency_varies: set a schedule; no_filing_spec: the knowledge base has no filing rules for the regime yet). nextPeriodStart and nextDueAt are the earliest period still to file.

At a glance

REST: GET /api/v1/filing_schedules
MCP tool: filing_periods_schedules
Operation ID: filing_periods.schedules
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

Query parameters

Field	Type	Required	Description
`regimeId`	string	No	Only this regime.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].object`	`"filing_schedule"`
`data[].regimeId`	string
`data[].registrationId`	`regn_…` ID
`data[].registrationState`	one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered`
`data[].reportKind`	one of `eu_oss`, `eu_domestic`, `uk_vat`, `ch_mwst`, `generic`, `us_state` or null
`data[].filingSpecId`	string or null
`data[].currency`	string or null
`data[].frequency`	one of `monthly`, `quarterly`, `annual` or null
`data[].startMonth`	integer or null
`data[].due`	object or null
`data[].source`	object or null
`data[].problem`	one of `no_filing_spec`, `frequency_varies`, `due_other`, `due_days_missing`, `due_nth_day_missing`, `due_months_missing`, `regime_missing` or null
`data[].filingSpec`	object or null
`data[].registrationSchedule`	object or null
`data[].nextPeriodStart`	date-time or null
`data[].nextDueAt`	date-time or null
`data[].periods`	integer

Examples

The entity's filing schedules

HTTP

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

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "object": "filing_schedule",
      "regimeId": "EU_OSS_UNION",
      "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk",
      "registrationState": "registered",
      "reportKind": "eu_oss",
      "filingSpecId": "kn_01m4tx5nj8emwbyf7y9vcf47y8",
      "currency": "EUR",
      "frequency": "quarterly",
      "startMonth": 1,
      "due": {
        "kind": "end_of_following_month",
        "days": null,
        "nthDay": null,
        "months": null,
        "description": "the last day of the month after the period"
      },
      "source": {
        "frequency": "filing_spec",
        "due": "filing_spec"
      },
      "problem": null,
      "filingSpec": {
        "frequency": "quarterly",
        "due": {
          "kind": "end_of_following_month",
          "days": null,
          "nthDay": null,
          "months": null,
          "description": "the last day of the month after the period"
        }
      },
      "registrationSchedule": null,
      "nextPeriodStart": "2026-06-30T22:00:00.000Z",
      "nextDueAt": "2026-10-31T22:59:59.000Z",
      "periods": 3
    },
    {
      "object": "filing_schedule",
      "regimeId": "GB_VAT_NETP",
      "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47y6",
      "registrationState": "registered",
      "reportKind": "uk_vat",
      "filingSpecId": "kn_01m4tx5nj8emwbyf7y9vcf47y7",
      "currency": "GBP",
      "frequency": "quarterly",
      "startMonth": 2,
      "due": {
        "kind": "months_and_days_after_period_end",
        "days": 7,
        "nthDay": null,
        "months": 1,
        "description": "1 month and 7 days after the period ends"
      },
      "source": {
        "frequency": "registration",
        "due": "registration"
      },
      "problem": null,
      "filingSpec": {
        "frequency": "quarterly",
        "due": {
          "kind": "other",
          "days": null,
          "nthDay": null,
          "months": null,
          "description": "a rule Ownrecord can't compute: set a due rule on the registration"
        }
      },
      "registrationSchedule": {
        "frequency": "quarterly",
        "startMonth": 2,
        "due": {
          "kind": "months_and_days_after_period_end",
          "days": 7,
          "nthDay": null,
          "months": 1,
          "description": "1 month and 7 days after the period ends"
        },
        "note": "Stagger 2 per the VAT registration certificate",
        "setAt": "2026-10-20T09:00:00.000Z",
        "setBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa"
      },
      "nextPeriodStart": "2026-07-31T23:00:00.000Z",
      "nextDueAt": "2026-12-07T23:59:59.000Z",
      "periods": 2
    }
  ]
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`regimeId` is malformed.	Fix the fields listed in `details.issues` and send the request again.
`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`	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: 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#

The entity's filing schedules#

Errors#