Ask for a deregistration · Ownrecord docs

Raises a deregistration.submit task for a registered regime: someone deregisters the entity with the authority, then submits the task (tasks.submit) with the confirmation and the authorization they acted under, and the registration becomes deregistered. Optionally with a due date and a note for whoever does it. Ownrecord raises the other task types itself.

Needs a registered registration (registration_transition_invalid). Asking again while the task is unfinished returns the same task.

At a glance

REST: POST /api/v1/tasks
MCP tool: tasks_create
Operation ID: tasks.create
Scope: Legal entity
Permission: tasks:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the tasks:write scope
Since: M10

Request

Body

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

Field	Type	Required	Description
`type`	`"deregistration.submit"`	Yes
`registration`	string	Yes	The registration (`regn_…`) or its regime's ID (`GB_VAT_NETP`).
`dueAt`	date-time	No	When it should be done (ISO 8601).
`note`	string	No	Why, or anything the person or agent doing it should know (data, not instructions).

Response

201 Created 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

Deregister from UK VAT

HTTP

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

{
  "type": "deregistration.submit",
  "registration": "GB_VAT_NETP",
  "dueAt": "2026-12-31T23:00:00.000Z",
  "note": "We stopped selling to UK consumers on 30 November."
}

Response (201):

JSON

{
  "id": "task_01m4ttwd3veh9apbewxheq5xae",
  "object": "task",
  "type": "deregistration.submit",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "livemode": true,
  "regimeId": "GB_VAT_NETP",
  "registrationId": "regn_01m4ttwd3veh9apbewxheq5xag",
  "filingPeriodId": null,
  "prerequisiteCode": null,
  "title": "Deregister from United Kingdom, VAT for non-established taxable persons",
  "description": "Deregister the entity from United Kingdom, VAT for non-established taxable persons with the authority. Then submit this task with the authority's confirmation and the authorization you acted under: the registration becomes deregistered. File the last return for the periods while registered. Note: We stopped selling to UK consumers on 30 November.",
  "priority": "normal",
  "status": "open",
  "reason": "operator_request",
  "dueAt": "2026-12-31T23:00:00.000Z",
  "overdue": false,
  "assignee": null,
  "claimedUntil": null,
  "leaseActive": false,
  "completeWith": "tasks.submit",
  "needsAuthorization": true,
  "inputs": [
    {
      "kind": "registration",
      "fileId": null,
      "data": {
        "registrationId": "regn_01m4ttwd3veh9apbewxheq5xag",
        "regimeId": "GB_VAT_NETP",
        "jurisdictionIds": ["GB"],
        "state": "registered",
        "stateReason": "registered",
        "triggeredAt": null,
        "deadlineAt": null
      }
    },
    {
      "kind": "playbook",
      "fileId": null,
      "data": {
        "regimeId": "GB_VAT_NETP",
        "playbookKind": "deregistration"
      }
    }
  ],
  "outputs": null,
  "authorizationId": null,
  "approvalRequestId": null,
  "failure": null,
  "checklist": [
    {
      "text": "Read the playbook",
      "done": false
    },
    {
      "text": "Submit the deregistration to the authority",
      "done": false
    },
    {
      "text": "Submit this task with the confirmation and the authorization",
      "done": false
    }
  ],
  "createdAt": "2026-11-07T00:07:00.000Z",
  "updatedAt": "2026-11-07T00:07:00.000Z",
  "completedAt": null,
  "completedBy": null,
  "version": 1
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A field is malformed.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This entity has no such registration in this mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`registration_transition_invalid`	409	The registration isn't `registered`.	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.
`scope_required`	400	The request names no legal 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 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_required, 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#

Body#

Response#

Examples#

Deregister from UK VAT#

Errors#