---
title: "Deletes a custom role, like Roles → Delete in the app."
method: DELETE
path: "/api/v1/roles/{id}"
tags: ["Roles"]
---

# Deletes a custom role, like Roles → Delete in the app.

`DELETE /api/v1/roles/{id}`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/roles/{id}`
- Auth: HTTP bearer

Requires `ManageRoles` and an `Idempotency-Key` header. The role and its permissions are
removed for good on the hosted web app and API (there is no restore); installed desktop and
back-office apps that sync the organization may keep listing it until they are reset. Built-in roles (`OrganizationAdmin`, `Manager`,
`User`) have no id and cannot be deleted. While any account (active or deactivated) still holds
the role the delete is refused with `409`, whose `detail` says how many; either remove it
from them first (`PATCH /api/v1/users/{id}` with the remaining `customRoleIds`) or repeat
with `?unassignUsers=true` to take it away from every account in the same call. Those accounts
are refused its permission-gated actions at once; menus in a signed-in browser session catch up
within about 5 minutes, and API keys minted by them lose the permissions within 60 seconds. A
`409` is stored against its `Idempotency-Key` for 24 hours like any other result, so
every retry after a `409` (whether you unassigned the holders first or add
`?unassignUsers=true`) needs a new `Idempotency-Key`; resending the old one replays the
`409`.
Example: `DELETE /api/v1/roles/4?unassignUsers=true`.

## Path parameters

- `id` integer, required

## Query parameters

- `unassignUsers` boolean

## Response `200`

Deleted; `id` is the deleted role and `message` names how many accounts lost it.

- ApiOperationResponse: Body of a successful workflow-style write that has no richer resource to return (assign, start, complete, void…). Id is the affected resource's id; Warning carries a non-fatal note from the service (e.g. an email that could not be sent).
  - `id` integer: Id of the resource the operation acted on (e.g. the job id).
  - `message` string, nullable: Human-readable confirmation from the service (e.g. "Job started."). May be null.
  - `warning` string, nullable: Non-fatal problem encountered while completing the operation (e.g. a notification email that could not be sent). Null when there was none.

## Other responses

- `400`: Missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: No such custom role in this organization (also built-in and already-deleted roles).
- `409`: Accounts still hold the role and `unassignUsers` was not set, or the key's creator is unknown on this server.
- `429`: Too Many Requests
- `500`: The role could not be removed from an account or deleted; nothing after the failing step ran — retry.

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)