Update a compliance task · Ownrecord docs

Changes an unfinished task: assign it to a member (or unassign with null), set or remove its due date, change its priority, tick checklist items (send the whole checklist), or move it between open and in_progress, or to cancelled when it isn't needed. Finished tasks (done, failed, cancelled) and tasks waiting for an approval don't change (task_status_invalid); finish a task with tasks.complete or tasks.submit.

While someone holds the task's lease (tasks.claim), only they can change it (task_claimed). When the holder moves it back to open, cancels it or assigns it to someone else, the lease ends.

The assignee must be a member who may work on the entity's tasks in this mode (owners, admins, tax managers and finance at the organization or this entity). An overdue prerequisite task raises PREREQ_OVERDUE; moving its due date reports it again only when the new date passes.

At a glance

REST: PATCH /api/v1/tasks/{id}
MCP tool: tasks_update
Operation ID: tasks.update
Scope: Organization, or one of its legal entities or brands
Permission: tasks:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
Modes: Test and live
Authentication: API key with the tasks:write scope
Since: M7

Request

Path parameters

Field	Type	Description
`id`	`task_…` ID

Body

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

Field	Type	Required
`assignee`	object or null	No
`dueAt`	date-time or null	No
`priority`	one of `low`, `normal`, `high`, `urgent`	No
`status`	one of `open`, `in_progress`, `cancelled`	No
`checklist`	array of object	No
`checklist[].text`	string	Yes
`checklist[].done`	boolean	Yes
`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

Assign the task and start it

HTTP

PATCH /api/v1/tasks/task_01m4ttwd3veh9apbewxheq5xae
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "assignee": {
    "type": "user",
    "id": "usr_01m4ttwd3veh9apbewxheq5xh6"
  },
  "status": "in_progress",
  "expectedVersion": 1
}

Response (200):

JSON

{
  "id": "task_01m4ttwd3veh9apbewxheq5xae",
  "object": "task",
  "type": "registration.submit",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "livemode": true,
  "regimeId": "EU_OSS_NON_UNION",
  "registrationId": "regn_01m4ttwd3veh9apbewxheq5xag",
  "filingPeriodId": null,
  "prerequisiteCode": null,
  "title": "Submit the EU One-Stop Shop, non-Union scheme registration",
  "description": "The grace deadline for EU One-Stop Shop, non-Union scheme wasn't met, so new consumer sales were blocked automatically. The legal deadline is 2026-11-10. Existing customers' renewals, top-ups and refunds continue and are taxed pending registration. Submit the registration, then record it here.",
  "priority": "urgent",
  "status": "in_progress",
  "reason": "auto_blocked",
  "dueAt": "2026-11-10T22:59:59.000Z",
  "overdue": false,
  "assignee": {
    "type": "user",
    "id": "usr_01m4ttwd3veh9apbewxheq5xh6"
  },
  "claimedUntil": null,
  "leaseActive": false,
  "completeWith": "tasks.submit",
  "needsAuthorization": true,
  "inputs": [
    {
      "kind": "registration",
      "fileId": null,
      "data": {
        "registrationId": "regn_01m4ttwd3veh9apbewxheq5xag",
        "regimeId": "EU_OSS_NON_UNION",
        "jurisdictionIds": ["EU"],
        "state": "blocked_b2c",
        "stateReason": "grace_deadline_missed",
        "triggeredAt": "2026-10-14T09:00:00.000Z",
        "deadlineAt": "2026-11-10T22:59:59.000Z"
      }
    },
    {
      "kind": "registration_packet",
      "fileId": null,
      "data": {
        "registrationId": "regn_01m4ttwd3veh9apbewxheq5xag",
        "regimeId": "EU_OSS_NON_UNION"
      }
    },
    {
      "kind": "playbook",
      "fileId": null,
      "data": {
        "regimeId": "EU_OSS_NON_UNION",
        "playbookKind": "registration"
      }
    }
  ],
  "outputs": null,
  "authorizationId": null,
  "approvalRequestId": null,
  "failure": null,
  "checklist": [
    {
      "text": "Check the prerequisites and read the playbook",
      "done": true
    },
    {
      "text": "Submit the registration application to the authority",
      "done": false
    },
    {
      "text": "Submit this task with the receipt and the authorization",
      "done": false
    },
    {
      "text": "Confirm the registration when the number arrives",
      "done": false
    }
  ],
  "createdAt": "2026-11-07T00:07:00.000Z",
  "updatedAt": "2026-11-08T09:15:00.000Z",
  "completedAt": null,
  "completedBy": null,
  "version": 2
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	Nothing to change, or a value is invalid.	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_status_invalid`	409	The task is finished, or it waits for an 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_assignee_invalid`	400	The person isn't a member who may work on this entity's tasks.	Assign a member of the organization who may work on tasks for this legal entity in this mode (an owner, an admin, a tax manager or finance, at the organization or this entity).
`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 compliance tasks 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, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Assign the task and start it#

Errors#