Submit a compliance task · Ownrecord docs

Submits the outcome of a task whose completion changes a registration or a filing period, with the evidence: the task is done and, in the same transaction, the linked state changes:

Task	`reference`	Changes
`filing.submit`	the return's reference (required)	the period becomes `submitted`
`filing.pay`	the payment reference (required); `paidOn` (default today)	the period becomes `paid`; the ledger moves the tax payable to the bank
`registration.submit`	the application or receipt number	in grace, the application is marked submitted (the deadline is met); then `registration.confirm` is raised
`registration.confirm`	the registration number (required); `effectiveFrom` (required)	the registration becomes `registered`
`deregistration.submit`	the authority's reference	the registration becomes `deregistered`

Evidence: receipt files uploaded to the task (tasks.documents.upload, then outputs.files), more outputs.references, outputs.submittedAt (default now) and outputs.notes. They are attached to the filing period's receipts or the registration's evidence. Registration tasks need a receipt file or a reference as proof. *.submit tasks reference the authorization the work was done under (authorizationId): valid now, for this entity, mode and the task's regime. Ownrecord records it; it doesn't grant it.

Compliance tier (spec §41.4): under your approval policy the call may answer approval_required (HTTP 202): nothing changes yet, the task waits (awaiting_approval), and once a person approves it runs exactly as sent. Dry-run it first. The caller must also be allowed to change the linked registration (registrations:write) or filing period (filings:write). People need a sign-in within the last 15 minutes. While someone else holds the task's lease, only they can submit it.

At a glance

REST: POST /api/v1/tasks/{id}/submit
MCP tool: tasks_submit
Operation ID: tasks.submit
Scope: Organization, or one of its legal entities or brands
Permission: tasks:write
Risk tier: compliance
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the tasks:write scope
Fresh sign-in: In the console, a sign-in within the last 15 minutes
Since: M10

Request

Path parameters

Field	Type	Description
`id`	`task_…` ID

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`reference`	string	No	The authority's reference for this task (see the table).
`effectiveFrom`	string	No	`registration.confirm`: the first day the registration is effective.
`paidOn`	string	No	`filing.pay`: the day the tax was paid, in the period's time zone.
`authorizationId`	`atz_…` ID	No	The authorization the work was done under (required for `*.submit` tasks).
`outputs`	object	No
`outputs.references`	object	No
`outputs.submittedAt`	date-time	No
`outputs.files`	array of `file_…` ID	No
`outputs.notes`	string	No
`expectedVersion`	integer (at least 1)	No

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`task_…` ID
`object`	`"task"`
`type`	one of 12 values, e.g. `registration.prerequisites`, `registration.prepare`, `registration.submit` (all in the OpenAPI document)
`entityId`	`ent_…` ID
`livemode`	boolean
`regimeId`	string or null
`registrationId`	`regn_…` ID or null
`filingPeriodId`	`fp_…` ID or null
`prerequisiteCode`	string or null
`title`	string
`description`	string or null
`priority`	one of `low`, `normal`, `high`, `urgent`
`status`	one of `open`, `claimed`, `in_progress`, `awaiting_approval`, `done`, `failed`, `cancelled`
`reason`	one of 11 values, e.g. `auto_blocked`, `existing_customer_sale`, `prerequisite_open` (all in the OpenAPI document) or null
`dueAt`	date-time or null
`overdue`	boolean
`assignee`	object or null
`claimedUntil`	date-time or null
`leaseActive`	boolean
`completeWith`	one of `tasks.complete`, `tasks.submit`
`needsAuthorization`	boolean
`inputs`	array of object
`inputs[].kind`	string
`inputs[].fileId`	`file_…` ID or null
`inputs[].data`	object or null
`outputs`	object or null
`authorizationId`	`atz_…` ID or null
`approvalRequestId`	`apr_…` ID or null
`failure`	object or null
`checklist`	array of object
`checklist[].text`	string
`checklist[].done`	boolean
`createdAt`	date-time
`updatedAt`	date-time
`completedAt`	date-time or null
`completedBy`	string or null
`version`	integer (at least 1)

Examples

The Q3 OSS return was filed

An agent's call answers approval_required under the default policy; this is the approved run's result.

HTTP

POST /api/v1/tasks/task_01m4ttwd3veh9apbewxheq5xa9/submit
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "reference": "HR/HR12345678901/Q3.2026",
  "authorizationId": "atz_01m4ttwd3veh9apbewxheq5xa3",
  "outputs": {
    "files": [
      "file_01m4ttwd3veh9apbewxheq5xah"
    ],
    "submittedAt": "2026-10-15T09:10:00.000Z"
  }
}

Response (200):

JSON

{
  "id": "task_01m4ttwd3veh9apbewxheq5xa9",
  "object": "task",
  "type": "filing.submit",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "livemode": true,
  "regimeId": "EU_OSS_UNION",
  "registrationId": "regn_01m4ttwd3veh9apbewxheq5xa8",
  "filingPeriodId": "fp_01m4ttwd3veh9apbewxheq5xa7",
  "prerequisiteCode": null,
  "title": "File the One-Stop Shop, Union scheme 2026-Q3 return",
  "description": "File the One-Stop Shop, Union scheme 2026-Q3 return with the authority using the filing package, by 2026-10-31. Then submit this task with the return's reference, the portal's confirmation and the authorization you acted under: the period becomes submitted.",
  "priority": "high",
  "status": "done",
  "reason": "period_ended",
  "dueAt": "2026-10-31T22:59:59.000Z",
  "overdue": false,
  "assignee": {
    "type": "agent",
    "id": "agt_01m4ttwd3veh9apbewxheq5xa6"
  },
  "claimedUntil": null,
  "leaseActive": false,
  "completeWith": "tasks.submit",
  "needsAuthorization": true,
  "inputs": [
    {
      "kind": "filing_period",
      "fileId": null,
      "data": {
        "filingPeriodId": "fp_01m4ttwd3veh9apbewxheq5xa7",
        "regimeId": "EU_OSS_UNION",
        "periodKey": "2026-Q3",
        "dueDate": "2026-10-31",
        "dueAt": "2026-10-31T22:59:59.000Z"
      }
    },
    {
      "kind": "filing_package",
      "fileId": null,
      "data": {
        "filingPeriodId": "fp_01m4ttwd3veh9apbewxheq5xa7"
      }
    },
    {
      "kind": "playbook",
      "fileId": null,
      "data": {
        "regimeId": "EU_OSS_UNION",
        "playbookKind": "filing"
      }
    }
  ],
  "outputs": {
    "references": {
      "return": "HR/HR12345678901/Q3.2026"
    },
    "submittedAt": "2026-10-15T09:10:00.000Z",
    "files": ["file_01m4ttwd3veh9apbewxheq5xah"],
    "notes": null
  },
  "authorizationId": "atz_01m4ttwd3veh9apbewxheq5xa3",
  "approvalRequestId": "apr_01m4ttwd3veh9apbewxheq5xa1",
  "failure": null,
  "checklist": [
    {
      "text": "Download the filing package",
      "done": false
    },
    {
      "text": "File the return in the authority's portal",
      "done": false
    },
    {
      "text": "Submit this task with the reference, the confirmation and the authorization",
      "done": false
    }
  ],
  "createdAt": "2026-10-01T00:23:00.000Z",
  "updatedAt": "2026-10-15T11:02:00.000Z",
  "completedAt": "2026-10-15T11:02:00.000Z",
  "completedBy": "agt_01m4ttwd3veh9apbewxheq5xa6",
  "version": 5
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A field is malformed, a required reference or date is missing, or a date is in the future.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	No task with this ID in this organization, entity and mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`task_complete_required`	400	The task doesn't change a registration or filing period: use `tasks.complete`.	Call `tasks.complete` with the task's outputs.
`task_status_invalid`	409	The task is finished, or it waits for another approval.	Reload the task: finished tasks (`done`, `failed`, `cancelled`) don't change, and a task waiting for an approval changes only through that approval. `details.status` is the task's status.
`task_claimed`	409	Someone else holds the task's lease.	Work on another task (`tasks.list` with `claimable: true`), or try again after `details.claimedUntil`: an expired lease frees the task. `details.assignee` is who holds it.
`task_authorization_required`	400	A `*.submit` task without `authorizationId`.	Record who may act for the entity under this regime (`authorizations.create`) and pass its ID as `authorizationId`. Ownrecord records the authorization; it doesn't grant it.
`task_authorization_invalid`	400	The authorization isn't valid now for this entity, mode and regime (`details.problem`).	Use an authorization of this legal entity and mode that is valid now and covers the task's regime. `details.problem` is `revoked`, `expired`, `not_yet_valid`, `regime_not_covered`, `other_entity` or `other_mode`.
`task_output_file_not_found`	400	A receipt isn't a document of the task (upload it with `tasks.documents.upload`).	Upload the receipt to the task first (`tasks.documents.upload`) and pass its `file_…` ID, or record the receipt number as a reference instead. `details.fileId` is the ID that wasn't found.
`filing_period_status_invalid`	409	The period isn't `prepared` (submit) or `submitted` (pay).	Reload the period and check its `status`: `details.allowed_from` lists the statuses the action needs. Periods go open → locked → prepared → submitted → paid.
`registration_transition_invalid`	409	The registration can't make this change now (e.g. it isn't registered, for a deregistration).	Check the registration's state (`details.state`): `details.allowed_from` lists the states the action needs. Reload the registration and try the action that fits its state.
`registration_details_invalid`	400	The registration number, effective date or proof is missing.	Fill in the field named in `param`: the registration number, the date it is effective from, or at least one proof file.
`approval_required`	202	Your approval policy needs a person to approve the submission first (HTTP 202).	Nothing ran yet. An approver reviews `approval.summary` and the dry-run result in the console (`approval.approveUrl`). Poll `GET /approvals/{id}` or watch for the `approval.resolved` event; sending the same request again with the same Idempotency-Key returns the same approval.
`fresh_auth_required`	403	Your last sign-in is older than 15 minutes.	Sign in again, then repeat the action within 15 minutes.
`version_conflict`	409	The task changed since `expectedVersion`, or at the same moment.	Fetch the object again and retry the change.
`permission_denied`	403	You can't work on tasks here, or can't change the linked registration or filing period.	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, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

The Q3 OSS return was filed#

Errors#