Skip to content

Delete User Roles

Delete User Roles API

Article ID RC-API-27 — Delete User Roles API
Domain API
Applies To All REDCap projects
Requires Any supported version
Verified Against REDCap v17.4.1 (Standard) / v17.3.7 (LTS) — changelog review; page not re-captured
Prerequisite RC-API-01 — REDCap API
Version 1.2
Last Updated 2026
Author See KB-SOURCE-ATTESTATION.md
Source REDCap API v16.1.3 official documentation examples
Related Topics RC-API-01 — REDCap API; RC-USER-01 — User Rights: Overview & Three-Tier Access; RC-USER-03 — User Rights: Configuring User Privileges
Synonyms how do i delete user roles via the api; delete user roles api call; remove custom roles from a project through the api; api method to delete role definitions by unique role name; bulk delete user roles with the api; remove role templates programmatically; api endpoint to delete user roles; delete a role and unassign its users via api

1. Overview

The Delete User Roles API method removes custom user roles from your project. You provide a list of role IDs (the unique_role_name values) to delete.

Unassign users first. In the user interface REDCap refuses to delete a role that still has users assigned to it (see RC-USER-02 §130 and RC-USER-04 §124); the role must be emptied first, by moving its users to another role or to individual rights. Whether this API method enforces the same guard or proceeds regardless has not been verified. Treat unassigning first as the required step either way: if the guard applies, the call fails until you do it, and if it does not, the users silently lose the permissions the role granted.

Use this method to clean up unused roles, automate role lifecycle management, or revoke access granted through a specific role.

2. Parameters

Parameter Required Description
token Required Your project API token. Requires API Import and User Rights rights.
content Required Always 'userRole' for this method.
action Required Always 'delete' for this method.
roles[0], roles[1], ... Required Array of role IDs to delete (the unique_role_name values). Pass as roles[0]=U-527D39JXAC&roles[1]=U-XXXXX, etc.

3. Request Examples

3.1 Python

from config import config
import requests, json

fields = {
    'token': config['api_token'],
    'content': 'userRole',
    'action': 'delete',
    'format': 'json',
    'roles[0]': 'U-522RX7WM49'
}

r = requests.post(config['api_url'],data=fields)
print('HTTP Status: ' + str(r.status_code))
print(r.text)

3.2 R

#!/usr/bin/env Rscript

source('config.R')
library(RCurl)

result <- postForm(
    api_url,
    token=api_token,
    content='userRole',
    action='delete',
    'roles[0]'='U-522RX7WM49'
)
print(result)

3.3 cURL

#!/bin/sh

. ./config

DATA="token=$API_TOKEN&content=userRole&action=delete&format=json&roles[0]=U-522RX7WM49"

$CURL -H "Content-Type: application/x-www-form-urlencoded" \
      -H "Accept: application/json" \
      -X POST \
      -d $DATA \
      $API_URL

3.4 PHP

<?php

include 'config.php';

$fields = array(
    'token'   => $GLOBALS['api_token'],
    'content' => 'userRole',
    'action'  => 'delete',
    'format'  => 'json',
    'roles'  => array('U-522RX7WM49'),
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $GLOBALS['api_url']);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields, '', '&'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); // Set to TRUE for production use
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_AUTOREFERER, true);
curl_setopt($ch, CURLOPT_MAXREDIRS, 10);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);

$output = curl_exec($ch);
print $output;

Note: In PHP examples, CURLOPT_SSL_VERIFYPEER is shown as FALSE for compatibility. Set it to TRUE in production. See RC-API-01 — REDCap API — Section 3.5.

4. Response

On success, the API returns a count of roles deleted. For example: 1 means one role was removed from the project. If a role ID does not exist in the project, it is ignored and does not affect the response.

5. Common Questions

Q: What happens to users assigned to a deleted role?

A: The role is removed, but the users are not deleted. However, they lose the permissions granted by that role. You must either reassign them to another role or set individual permissions to maintain their access.

Q: What is the unique_role_name?

A: It's the system-generated alphanumeric ID assigned to the role (e.g., U-522RX7WM49). To find this ID, export existing roles using the Export User Roles method (RC-API-25 — Export User Roles API).

Q: What if I try to delete a role that doesn't exist?

A: The API ignores the role ID and does not report an error. If you delete a role and the API returns 0, it means the role was not found in the project.

Q: Can I delete multiple roles at once?

A: Yes. Pass multiple role IDs using array syntax: roles[0]=U-XXXXX&roles[1]=U-YYYYY. All roles in the array will be deleted in a single call.

Q: Can I undo a role deletion?

A: No. Role deletion is permanent. To restore a role, you must import it again using the Import User Roles method (RC-API-26 — Import User Roles API) with the same or similar definition.

6. Common Mistakes & Gotchas

Deleting a role without reassigning its users. Empty the role before calling this method. Use RC-API-55 — Export User-Role Assignments to list who is currently assigned, then move those users to another role or give them individual permissions. The interface blocks deletion of a populated role outright; it is unverified whether this API method does the same, so do not rely on the call failing to protect you from a mistake.

Confusing role labels with role IDs. The unique_role_name is the system ID (e.g., U-522RX7WM49), not the human-readable label (e.g., 'Project Manager'). Use the ID, not the label, in the delete request.

Expecting an error when deleting a non-existent role. The API does not return an error if a role ID is not found; it simply returns 0. Check the response count to verify the expected number of roles were deleted.

Forgetting the User Rights permission. This method requires both API Import and User Rights rights. If your token lacks User Rights, the deletion will fail.

Inadvertently deleting the wrong role. Role IDs are alphanumeric and easy to mistype. Always verify the correct role ID by exporting existing roles before deletion.