API Reference
Support from Community ↗︎Back to Pipefy ↗︎

Delete Custom Role

Delete a custom role from an organization.

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

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 (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

2. Get the role ID

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

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

Step 2: Run the mutation

Operation

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

Arguments (input)

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

Example (realistic values)

{
  "input": {
    "roleId": "149"
  }
}

Expected response

{
  "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

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

2. Insufficient permissions

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

3. Organization plan doesn't support custom roles

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

4. Role not found

{
  "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