> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Workforce Employees (v2)

> Delete up to 5,000 employees by id, with their contracts, remunerations, trainings and absences, as an ingest job

[← Own Workforce API](/api-reference/own-workforce/overview)

Delete employees by id, with everything recorded about them: contracts, remunerations, trainings, absences and
accidents. The request checks every id and answers `202 Accepted` with an
[ingest job](/api-reference/ingest-jobs/get) that deletes them in the background. Follow it with
[`GET /v2/ingest-jobs/{id}`](/api-reference/ingest-jobs/get) or the
[`ingest_job.finished`](/api-reference/webhooks/overview) webhook.

The ids are the ones [Create Workforce Employees (v2)](/api-reference/own-workforce/employees-create-v2) answers, or
the `id`s of [List Workforce Employees](/api-reference/own-workforce/list).

<Warning>
  **Permanent.** Deleted employees and their records cannot be recovered. Use `dry_run=true` first if you are not sure.
</Warning>

<Warning>
  **Beta.** Part of the bulk ingest API, currently in beta. The contract may still change before general availability.
</Warning>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v2/own-workforce/employees/delete" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Idempotency-Key: 8d7c6b5a-4938-4271-a60f-e9d8c7b6a594" \
    -H "Content-Type: application/json" \
    -d '{"ids": ["6f5e4d3c-2b1a-4f09-8e7d-6c5b4a392817"]}'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import uuid

  import requests

  response = requests.post(
      "https://api.dcycle.io/v2/own-workforce/employees/delete",
      headers={
          "x-api-key": os.environ["DCYCLE_API_KEY"],
          "x-organization-id": os.environ["DCYCLE_ORG_ID"],
          "Idempotency-Key": str(uuid.uuid4()),  # keep it to retry this same batch
      },
      json={"ids": ["6f5e4d3c-2b1a-4f09-8e7d-6c5b4a392817"]},
      timeout=60,
  )
  response.raise_for_status()
  print(response.json()["id"])
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "status": "processing",
    "entity_type": "own_workforce",
    "operation": "delete",
    "source": "api_bulk",
    "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
    "chunks_total": 1,
    "chunks_done": 0,
    "created_at": "2026-10-19T09:20:31.877Z",
    "finished_at": null,
    "links": {
      "self": "/v2/ingest-jobs/9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "items": "/v2/ingest-jobs/9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d/items"
    }
  }
  ```

  ```json 422 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED",
    "title": "Unprocessable Entity",
    "status": 422,
    "code": "BULK_RECORDS_REJECTED",
    "detail": "1 of the submitted records are invalid; nothing was written.",
    "errors": [
      {
        "source_row_index": 0,
        "client_row_id": null,
        "error_code": "NOT_FOUND",
        "error_params": { "field": "ids", "value": "6f5e4d3c-2b1a-4f09-8e7d-6c5b4a392817" }
      }
    ],
    "rejected": 1,
    "request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
  }
  ```

  ```json 200 (dry_run=true) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "dry_run": true, "submitted": 1, "valid": 1 }
  ```
</ResponseExample>

## How it works

1. **The request checks every id.** One that does not exist, is outside your organization's perimeter or is repeated
   rejects the **whole** request with `422`, and nothing is deleted.
2. **The job deletes them in the background**, each with its contracts, remunerations, trainings (and their custom
   column values), absences and accidents.
3. **When every chunk is done** the job is `completed` (or `completed_with_errors`), and `ingest_job.finished` is sent
   with `"operation": "delete"`.

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key (see [Authentication](/api-reference/introduction#authentication)).
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization. Its employees, and those of the organizations under it that you can write to, can be deleted.
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  1 to 255 characters, unique per batch. A retry with the same key and body returns the original job (with
  `Idempotent-Replayed: true`); the same key with another body is `422 IDEMPOTENCY_KEY_REUSED`, and while the first
  request is still being processed `409 IDEMPOTENCY_KEY_IN_PROGRESS`.
</ParamField>

### Query Parameters

<ParamField query="dry_run" type="boolean" default="false">
  Check only: the same `422` for bad ids, nothing deleted, no job; `200` with `{"dry_run": true, "submitted": n,
      "valid": n}` when every id is valid.
</ParamField>

### Body Parameters

<ParamField body="ids" type="array[uuid]" required>
  Employee ids, 1 to 5,000, each once.
</ParamField>

## Response

`202 Accepted` with the job (`entity_type: own_workforce`, `operation: delete`) and a `Location` header to it.
[`GET /v2/ingest-jobs/{id}/items`](/api-reference/ingest-jobs/list-items) has one item per employee, in the order sent;
an item is `failed` with `DELETE_FAILED` when its employee was already gone by the time the job reached it.

## Errors

[Problem details](/api-reference/errors). Per-id codes in `errors[].error_code` of a `422 BULK_RECORDS_REJECTED`
(`source_row_index` is the position in `ids`):

| `error_code` | Cause |
| - | - |
| `NOT_FOUND` | The employee does not exist or is outside your organization's perimeter (both answer the same). |
| `DUPLICATE_ID` | The employee is already in the request. |

Request-level errors: `401` for a missing or invalid API key, `403 LOGGED_USER_NOT_MEMBER` when the key's user is not a
member of the organization, `422 REQUEST_VALIDATION_FAILED` for a malformed body (no `ids`, more than 5,000, no
`Idempotency-Key`), `422 IDEMPOTENCY_KEY_REUSED`, `409 IDEMPOTENCY_KEY_IN_PROGRESS`, and `429` beyond the
[rate limits](/api-reference/rate-limits).

## Limits

| Limit | Value |
| - | - |
| Ids per request | 1 to 5,000 |
| Employees per deletion chunk | 100 |

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Workforce Employees (v2)" icon="plus" href="/api-reference/own-workforce/employees-create-v2">
    Load employees, contracts and remunerations
  </Card>

  <Card title="List Workforce Employees" icon="table" href="/api-reference/own-workforce/list">
    Find the ids to delete
  </Card>

  <Card title="Get Ingest Job" icon="magnifying-glass" href="/api-reference/ingest-jobs/get">
    Follow the deletion
  </Card>

  <Card title="List Job Items" icon="list" href="/api-reference/ingest-jobs/list-items">
    The outcome of each id
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.