---
title: "Delete a candidate"
method: DELETE
path: "/candidates/{id}"
tags: ["Candidates"]
---

# Delete a candidate

`DELETE /candidates/{id}`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/candidates/{id}`
- Auth: HTTP bearer

Permanently erases a candidate and all associated data (GDPR cascade). Always asynchronous: returns `202` with a `candidates.remove` operation to poll. Requires `candidates.manage`.

## Path parameters

- `id` string, required: The candidate id.

## Response `202`

Deletion operation accepted.

- OperationResource
  - `id` string, required: Unique identifier for the object.
  - `object` 'operation', required: String representing the object's type. Objects of the same type share the same value.
  - `kind` 'domains.verify' | 'imports.parse' | 'imports.confirm' | 'subscribers.export' | 'subscribers.import' | 'custom_objects.records_import' | 'exports.generate' | 'candidates.remove' | 'employers.remove', required: Operation kind, identifying which workflow the operation runs.
  - `state` 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled', required: Current state of the operation.
  - `progress` OperationProgress, nullable, required: Snapshot of the operation's progress, or `null` if the operation does not report progress.
    - `percent` number: Progress as a percentage between 0 and 100, when the operation reports a percentage.
    - `message` string: Human-readable progress message, when available.
    - `processed` number: Number of items processed so far, when applicable.
    - `total` number: Total number of items to process, when known.
  - `result` object, nullable: A safe workflow result summary when the operation kind publishes one.
    - `totalRows` number, required
    - `created` number, required
    - `updated` number, required
    - `failed` number, required
    - `errors` object[], required
      - `rowIndex` number, required
      - `code` string, required
      - `message` string, required
  - `error` OperationErrorEnvelope, nullable, required: Error envelope, populated once the operation reaches `failed`. `null` otherwise.
    - `code` string, required: Machine-readable error code.
    - `message` string, required: Human-readable error message.
  - `createdAt` string, required: Time at which the operation was created. ISO 8601 datetime.
  - `updatedAt` string, required: Time at which the operation was last updated. ISO 8601 datetime.
  - `completedAt` string, nullable, required: Time at which the operation reached a terminal state, or `null` if it has not yet completed. ISO 8601 datetime.
  - `cancelRequested` boolean, required: Whether cancellation of the operation has been requested.
  - `resource` object, nullable, required: Stable product resource affected by the operation, or `null` when no public resource applies.
    - `object` 'company' | 'domain' | 'import' | 'employer' | 'candidate' | 'custom_object_type', required
    - `id` string, required

## Other responses

- `404`: Candidate not found.

## Changes

- **2026-10-19** `c34152c38176`: 1 info
  - added the optional property `error/upgrade` to the response with the `404` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/candidates/:id/delete.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)