> ## 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 Trainings (v2)

> Delete up to 5,000 trainings by id, asynchronously, as an ingest job

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

Delete trainings by id. 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 Trainings (v2)](/api-reference/own-workforce/trainings-create-v2) answers, or
the `id`s of [List Workforce Trainings](/api-reference/own-workforce/list-trainings). Deleting an employee deletes its
trainings too.

<Warning>
  **Permanent.** Deleted trainings 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/trainings/delete" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Idempotency-Key: 1f0e9d8c-7b6a-4594-8382-71605f4e3d2c" \
    -H "Content-Type: application/json" \
    -d '{"ids": ["3b2a1908-7f6e-4d5c-8b4a-392817160504"]}'
  ```

  ```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/trainings/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": ["3b2a1908-7f6e-4d5c-8b4a-392817160504"]},
      timeout=60,
  )
  response.raise_for_status()
  print(response.json()["id"])
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "7c6b5a49-3827-4160-95f4-e3d2c1b0a998",
    "status": "processing",
    "entity_type": "own_workforce_trainings",
    "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/7c6b5a49-3827-4160-95f4-e3d2c1b0a998",
      "items": "/v2/ingest-jobs/7c6b5a49-3827-4160-95f4-e3d2c1b0a998/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": "3b2a1908-7f6e-4d5c-8b4a-392817160504" }
      }
    ],
    "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, belongs to an employee 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**, with their custom column values.
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. The trainings of its employees, and of 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>
  Training ids, 1 to 5,000, each once.
</ParamField>

## Response

`202 Accepted` with the job (`entity_type: own_workforce_trainings`, `operation: delete`) and a `Location` header to it.
[`GET /v2/ingest-jobs/{id}/items`](/api-reference/ingest-jobs/list-items) has one item per training, in the order sent;
an item is `failed` with `DELETE_FAILED` when its training 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 training does not exist or its employee is outside your organization's perimeter (both answer the same). |
| `DUPLICATE_ID` | The training 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 |
| Trainings per deletion chunk | 500 |

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Workforce Trainings (v2)" icon="plus" href="/api-reference/own-workforce/trainings-create-v2">
    Create trainings in bulk
  </Card>

  <Card title="List Workforce Trainings" icon="table" href="/api-reference/own-workforce/list-trainings">
    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.