---
agentTools:
  projectIndex: https://developers.pipefy.com/llms.txt
---

# Delete Custom Role

Delete a custom role from an organization.

## Before You Begin

🔗 **Use the [GraphQL Playground](https://app.pipefy.com/graphiql)** to execute the queries in this guide.

➡️ **New to GraphQL?** Learn how to navigate the Playground with our **[Playground Basics Guide](https://developers.pipefy.com/reference/exploring-the-playground)**.

## Why this use case

When custom roles are no longer needed or have been replaced by other roles, you may need to delete them to maintain a clean role structure in your organization.

***

## Prerequisites

1. **Authentication**: Use a [Service Account token](https://developers.pipefy.com/reference/service-accounts) (Personal Access Tokens are deprecated).

2. **Permissions**: Ensure your token has the Super Admin Role.

3. **Organization ID**: Identify the Organization where the Custom Role exists.

4. **Plan**: Custom Roles are only available for Business, Enterprise and Unlimited plans.

5. **Role ID**: The ID of the custom role you want to delete.

## Step 1: Find Your Organization ID

### 1. Via Pipefy UI

* Open the Organization in your browser.
* The URL will include the Organization ID: <https://app.pipefy.com/organizations/123456789>.
* Organization ID = 123456789 (the number after /organizations/).

### 2. Get the role ID

You can find the role ID by querying the organization's roles:

```graphql
query {
  organization(id: "YOUR_ORG_ID") {
    roles {
      id
      name
      title
      isCustom
    }
  }
}
```

## Step 2: Run the mutation

### Operation

```graphql
mutation {
  deleteCustomRole(input: {
    roleId: "role_id"
  }) {
    success
  }
}
```

### Arguments (input)

* roleId: The ID of the custom role to delete (required)

### Example (realistic values)

```json
{
  "input": {
    "roleId": "149"
  }
}
```

### Expected response

```json
{
  "data": {
    "deleteCustomRole": {
      "success": true
    }
  }
}
```

## Important Notes

### What can be deleted

* ✅ **Custom roles only**: Only roles that were created as custom roles can be deleted
* ❌ **Default roles cannot be deleted**: The following default roles cannot be deleted:
  * `super_admin`
  * `admin`
  * `normal`
  * `company_guest`
  * `external_guest`

### Error scenarios

#### 1. Trying to delete a default role

```json
{
  "errors": [
    {
      "message": "Invalid input: Role (Default roles can't be deleted.)",
      "extensions": {
        "code": "INVALID_INPUT"
      }
    }
  ]
}
```

#### 2. Insufficient permissions

```json
{
  "errors": [
    {
      "message": "Permission denied",
      "extensions": {
        "code": "PERMISSION_DENIED"
      }
    }
  ]
}
```

#### 3. Organization plan doesn't support custom roles

```json
{
  "errors": [
    {
      "message": "Feature not allowed by organization plan",
      "extensions": {
        "code": "FEATURE_NOT_ALLOWED_BY_ORGANIZATION_PLAN"
      }
    }
  ]
}
```

#### 4. Role not found

```json
{
  "errors": [
    {
      "message": "Invalid input: Role (Invalid role.)",
      "extensions": {
        "code": "INVALID_INPUT"
      }
    }
  ]
}
```

## Best Practices

1. **Verify before deletion**: Always confirm the role ID and ensure it's a custom role before attempting deletion.

2. **Check role usage**: Consider if any users are currently assigned to this role, as deletion will remove the role from all users.

3. **Backup considerations**: If you need to restore the role later, you'll need to recreate it with the same permissions.

## Related Operations

* [Create Custom Role](https://developers.pipefy.com/reference/00-create-custom-role) - Learn how to create new custom roles