Bulk Delete Workforce Employees by Filters

Delete every own workforce employee matching a set of filters, guarded by the hash of the list you saw

POST /v1/own_workforces/bulk-delete-by-filters

Bulk Delete Workforce Employees by Filters

JavaScript

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({filter_hash: '<string>'})
};

fetch('https://api.dcycle.io/v1/own_workforces/bulk-delete-by-filters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

← Own Workforce API

Delete every employee matching a filter set, without collecting their ids first. The filters go in the query string — the same ones List Workforce Employees accepts — and the body carries the filter_hash that list returned.

Irreversible, and it cascades to contracts, remunerations, trainings and absence records. Always run the equivalent list call first and read total before deleting.

The filter_hash guard

filter_hash fingerprints the filters that produced a page — including consolidate_group, organization_id[] and the project scope. Send it back and the server recomputes the fingerprint from the filters on this request:

• they match → the delete proceeds over exactly the set you listed;
• they differ → 409 Conflict, and nothing is deleted.

That is what stops a client from listing one subsidiary, then widening the perimeter and deleting the whole group by accident. It guards against that drift, not against a caller who deliberately sends different filters — the tenant boundary is the organization scoping, not the hash. Take the hash verbatim from the list response.

No filter is required. With none, the delete covers every row of the perimeter the list showed: the header organization, or under consolidate_group the accepted family narrowed by organization_id[] (and the project scope, when it is on). The delete removes exactly the rows the list returns: an employee with no contract is not listed, so it is never deleted here either. Read total from the list before you delete.

Request

Headers

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

The same filters as the list endpoint. All of them are optional.

external_employee_id · string

Search by the employee identifier your HR system uses

file_id[] · array[string]

Filter by source upload file. The nil UUID matches rows with no file.

created_at_from · datetime

Only rows created at or after this instant

created_at_to · datetime

Only rows created at or before this instant

consolidate_group · boolean · default: "false"

Widen the perimeter to the accepted business family. Part of the hash.

organization_id[] · array[string]

Narrow a group-view delete to these organizations. Part of the hash.

Body

filter_hash · string · required

The filter_hash from the list response that showed you these rows

Response

Same shape as Bulk Delete Workforce Employees: success_count, success_ids, failed_count, failed_ids and message.

Example

cURL

curl -X POST "https://api.dcycle.io/v1/own_workforces/bulk-delete-by-filters?file_id[]=9f1c7f2a-64a1-4b2c-9d3e-70a5b8c1d2e3" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{"filter_hash": "b6d1f0c47a9e2d38"}'

Successful Response

{
  "success_count": 145,
  "success_ids": [
    "… 145 ids in total, abridged here …",
    "550e8400-e29b-41d4-a716-446655440000"],
  "failed_count": 0,
  "failed_ids": [],
  "message": "Deleted 145 own workforce records"
}

Common Errors

401 Unauthorized

Cause: the key is invalid, or it does not belong to the organization in x-organization-id — the two are looked up as a pair. A request carrying no credentials at all answers AUTH_REQUIRED instead.

{
  "detail": "Invalid API key for organization",
  "code": "INVALID_API_KEY"
}

403 Forbidden

Cause: the key’s owner is not an enabled member of the organization, or their role cannot write.

{
  "detail": "Logged User is not Member of Organization",
  "code": "LOGGED_USER_NOT_MEMBER"
}

409 Conflict

Cause: filter_hash does not match the filters on this request. Nothing was deleted. Re-list with the filters you intend, then retry with the fresh hash.

{
  "detail": "Filter hash mismatch. The filters have changed since the list was loaded. Please refresh and try again."
}

Related Endpoints

List employees

Where filter_hash comes from

Bulk delete by ids

When you already hold the ids