Data deletions

Preview and permanently delete one user's claim history, then follow the deletion to completion.

Data deletions remove one user's claim history from your workspace: their claims, the evaluations of those claims and their outcomes. Because import and export files can hold that user's data, a deletion also removes every export and every uploaded import file in the workspace. Preview a deletion first to see exactly what it covers, then request it. The deletion runs in the background. While it runs, AbuseZero refuses new evaluations for that user and new imports in the workspace. Every other user's evaluations continue as normal. For a walkthrough, see Export and delete data.

Deletion is permanent and can't be undone. Once a user's history is gone, their earlier claims no longer count against them, so they can qualify for your benefits again.

Only deletions of one user's history are available through the REST API. To delete a whole workspace, the workspace owner uses the dashboard.

With an OAuth token, every endpoint on this page also needs the signed-in member to have permission to delete data.

Examples on this page use a server client:

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({ key: process.env.ABUSEZERO_SECRET_KEY!, outage: "throw" });

The deletion object

{
  "object": "deletion",
  "id": "del_8b4f0d2a-6c1e-4a7b-9d3f-5e2a8c0b4d16",
  "kind": "subject",
  "state": "complete",
  "created_at": "2026-10-29T13:40:12.000Z",
  "completed_at": "2026-10-29T13:40:31.000Z"
}

Field	Type	Description
`object`	`"deletion"`	The object type.
`id`	string	The deletion ID, starting with `del_`.
`kind`	`subject` or `workspace`	`subject` deletes one user's history. `workspace` deletions are requested in the dashboard.
`state`	`pending` or `complete`	`pending` is still running. `complete` has finished.
`created_at`	string	When the deletion was requested.
`completed_at`	string or `null`	When the deletion finished.

The selector

Every request names the user with a selector.

Field	Type	Required	Limits	Description
`selector.kind`	`"subject"`	Yes		Delete one user's history.
`selector.user`	string	Yes	1 to 254 characters	The user to delete.
`selector.email`	boolean	Yes		`true` when `user` is an email address. `false` when it's your own user ID.

Name the user the way your evaluations did. If they sent subject.external_id, use that ID with email: false. If they sent only an email address, use the address with email: true. With email: true, a user that isn't a supported email address returns INVALID_EMAIL.

Preview a deletion

Shows what a deletion would cover. A preview changes nothing.

Method	Path	Scope	Idempotency-Key
`POST`	`/v1/data-deletions/preview`	`data_deletions:write`	Not used

Also available as abusezero data-deletions preview in the AbuseZero CLI, abusezero_preview_data_deletion on the AbuseZero MCP server and previewDataDeletion() in the AbuseZero Node.js SDK.

Request body

Field	Type	Required	Description
`selector`	object	Yes	The selector for the user.

Example

const preview = await abusezero.previewDataDeletion({
  selector: { kind: "subject", user: "user_4821", email: false },
});

Response

Returns 201.

{
  "object": "deletion_preview",
  "counts": {
    "claims": 3,
    "outcomes": 2,
    "files": 4
  },
  "confirmation": "5d41402abc4b2a76b9719d911017c592ae5f0c1e7d3b8a6f4c2e9d0b1a3f5e7c"
}

Field	Type	Description
`counts.claims`	integer	The user's claims that match.
`counts.outcomes`	integer	The user's outcomes that match.
`counts.files`	integer	Finished export files and uploaded import files stored in the workspace. The deletion removes all of them.
`confirmation`	string	Identifies this preview. It changes whenever the selector or the counts change, so two previews with the same value describe the same deletion.

Request a deletion

Starts deleting the user's history.

Method	Path	Scope	Idempotency-Key
`POST`	`/v1/data-deletions`	`data_deletions:write`	Required

Also available as abusezero data-deletions create in the AbuseZero CLI, abusezero_request_data_deletion on the AbuseZero MCP server and requestDataDeletion() in the AbuseZero Node.js SDK.

Request body

Field	Type	Required	Description
`selector`	object	Yes	The selector for the user.

Example

const deletion = await abusezero.requestDataDeletion(
  { selector: { kind: "subject", user: "user_4821", email: false } },
  "delete-user-4821",
);

Response

Returns 202. Retrieve the deletion at status_url until its state is complete.

{
  "object": "deletion",
  "id": "del_8b4f0d2a-6c1e-4a7b-9d3f-5e2a8c0b4d16",
  "status": "pending",
  "status_url": "/v1/data-deletions/del_8b4f0d2a-6c1e-4a7b-9d3f-5e2a8c0b4d16"
}

Errors

Code	Status	Meaning
`WORKSPACE_DELETION_EXCLUDED`	403	The selector asks to delete the whole workspace. Use the dashboard.
`PERMISSION_REQUIRED`	403	With an OAuth token, the signed-in member doesn't have permission to delete data. Ask the workspace owner.
`INVALID_EMAIL`	422	`email` is `true`, but `user` isn't a supported email address.
`IMPORTS_IN_PROGRESS`	409	An import in the workspace isn't `complete` or `cancelled`. Let it finish, or cancel it, then retry.
`DELETION_IN_PROGRESS`	409	This user's history, or the workspace, is already being deleted. Retry after that deletion completes.

For every other code, see REST API errors.

Retrieve a deletion

Method	Path	Scope	Idempotency-Key
`GET`	`/v1/data-deletions/{id}`	`data_deletions:read`	Not used

Also available as abusezero data-deletions get in the AbuseZero CLI, abusezero_get_data_deletion on the AbuseZero MCP server and call() in the AbuseZero Node.js SDK.

Path parameters

Parameter	Type	Description
`id`	string	The deletion ID, starting with `del_`.

Example

const deletion = await abusezero.call("/v1/data-deletions/del_8b4f0d2a-6c1e-4a7b-9d3f-5e2a8c0b4d16");

Response

Returns 200 with a deletion object.

Errors

Code	Status	Meaning
`RESOURCE_NOT_FOUND`	404	No deletion with this ID exists in the workspace.

List deletions

Returns deletions newest first.

Method	Path	Scope	Idempotency-Key
`GET`	`/v1/data-deletions`	`data_deletions:read`	Not used

Also available as abusezero data-deletions list in the AbuseZero CLI, abusezero_list_data_deletions on the AbuseZero MCP server and dataDeletions() in the AbuseZero Node.js SDK.

Query parameters

Parameter	Type	Required	Limits	Description
`limit`	integer	No	1 to 100, default 50	How many deletions to return.
`cursor`	string	No		The `next_cursor` from the previous page, unchanged.

Example

const page = await abusezero.dataDeletions();

Response

Returns 200.

{
  "object": "list",
  "data": [
    {
      "object": "deletion",
      "id": "del_8b4f0d2a-6c1e-4a7b-9d3f-5e2a8c0b4d16",
      "kind": "subject",
      "state": "complete",
      "created_at": "2026-10-29T13:40:12.000Z",
      "completed_at": "2026-10-29T13:40:31.000Z"
    }
  ],
  "next_cursor": null
}

Export and delete data

Export what you need before you delete it.

Imports

Finish or cancel open imports before deleting a user's history.

The deletion objectCopy Anchor Link

The selectorCopy Anchor Link

Preview a deletionCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Request a deletionCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

ErrorsCopy Anchor Link

Retrieve a deletionCopy Anchor Link

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

ErrorsCopy Anchor Link

List deletionsCopy Anchor Link

Query parametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

RelatedCopy Anchor Link

Export and delete data

Imports

On this page

The deletion object

The selector

Preview a deletion

Request body

Example

Response

Request a deletion

Request body

Example

Response

Errors

Retrieve a deletion

Path parameters

Example

Response

Errors

List deletions

Query parameters

Example

Response

Related