General API Info
Supported Methods
Arms
Data Access Groups
Events
Field Names
Files
File Repository
Instruments
Logging
Metadata
Projects
Records
Repeating Instruments and Events
Reports
REDCap
Surveys
Users & User Privileges
User Roles
REDCap API Documentation
Method Name
Import User-Role Assignments
Description
This method allows you to assign users to any user role.
NOTE: If you wish to modify an existing mapping, you *must* provide its unique username and role name. If the 'unique_role_name' column is not provided, user will not assigned to any user role. There should be only one record per username.
URL
Supported Request Method
Permissions Required
To use this method, you must have API Import/Update privileges *and* User Rights privileges in the project.
Parameters (case sensitive)
Required
token
The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.
The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.
content
userRoleMapping
userRoleMapping
action
import
import
format
csv, json, xml [default]
csv, json, xml [default]
data
Contains the attributes 'username' (referring to the existing unique username) and 'unique_role_name' (referring to existing unique role name) of each User-Role assignments to be modified, in which they are provided in the specified format. Note: If the project contains Data Access Groups, you may pass a third attribute 'data_access_group' with a valid unique DAG name of the DAG to which you wish to assign the user during the process of assigning them to a user role.
Contains the attributes 'username' (referring to the existing unique username) and 'unique_role_name' (referring to existing unique role name) of each User-Role assignments to be modified, in which they are provided in the specified format. Note: If the project contains Data Access Groups, you may pass a third attribute 'data_access_group' with a valid unique DAG name of the DAG to which you wish to assign the user during the process of assigning them to a user role.
JSON Example:
[{"username":"global_user","unique_role_name":""},
{"username":"ca_dt_person","unique_role_name":"U-2119C4Y87T"},
{"username":"fl_dt_person","unique_role_name":"U-2119C4Y87T"}]CSV Example:
username,unique_role_name
ca_dt_person,U-2119C4Y87T
fl_dt_person,U-2119C4Y87T
global_user,XML Example:
<?xml version="1.0" encoding="UTF-8" ?>
<items>
<item>
<username>ca_dt_person</username>
<unique_role_name>U-2119C4Y87T</unique_role_name>
</item>
<item>
<username>fl_dt_person</username>
<unique_role_name>U-2119C4Y87T</unique_role_name>
</item>
<item>
<username>global_user</username>
<unique_role_name></unique_role_name>
</item>
</items>
Optional
ReturnsreturnFormat
csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'xml'.
NOTE: Does not apply when importing as a background process (i.e., backgroundProcess=true). When using a background process, success:true (upon success) or success:false (upon failure) will be returned in the appropriate format (csv, json, xml).
csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'xml'.
NOTE: Does not apply when importing as a background process (i.e., backgroundProcess=true). When using a background process, success:true (upon success) or success:false (upon failure) will be returned in the appropriate format (csv, json, xml).
Number of User-Role assignments added or updated