# Update a compliance task > The tasks.update operation: PATCH /api/v1/tasks/{id} in the REST API and the tasks_update tool in the MCP server. 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 | Description | | ------------------ | ----------------------------------------- | -------- | ----------- | | `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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The task changed since `expectedVersion`, or at the same moment. | Fetch the object again and retry the change. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).