Managing User Groups

Groups allow sharing libraries of surveys, graphics, files, and messages between users. Administrators can use the user group APIs to create groups, add users to groups, and remove users from groups. For more information about user groups, see User Groups on the support site. For information about using libraries, see Library Overview.

Create Group

When you create a new group you must specify the group's name and group type. You can name the new group and assign it to a division (see User Divisions for more information about divisions). Besides the group's name, you need to specify the group's type. Group types specify default permissions to give new groups and can be created in the Administration user interface. See Group Types for more information. See Finding your Qualtrics IDs for information on how to retrieve IDs.

Code and Qualtrics Support

Our support team does not offer assistance or consultation on custom coding, but you can always try asking our community of dedicated users. If you’d like to know more about our custom coding services you can commission, please contact your Qualtrics Account Executive.

The following example shows how to create a new group:

# Create Group 

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN" # 1
dataCenter = "YOUR DATACENTER"  # 2

baseUrl = "https://{0}.qualtrics.com/API/v3/groups".format(dataCenter)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = { "type": "GT_1234567890",
  "name": "SW Users"
   }
response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

Add User to Group

The following example shows how to add a user to a group. You need both the group's ID and the user's ID. Use the List Groups API to obtain the group ID and the List Users API to obtain the user's ID.

# Add User to Group

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

groupId = "GR_1234567"

baseUrl = "https://{0}.qualtrics.com/API/v3/groups/{1}/members".format(dataCenter, groupId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = { "userId": "UR_123456789",
   }
response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

Remove User from Group

The following example shows how to remove a user from a specific group. You need the user ID and group ID of the user and group.

# Remove User from Group

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

groupId = "GR_1234567890"
userId = "UR_1234567890"

baseUrl = "https://{0}.qualtrics.com/API/v3/groups/{1}/members/{2}".format(dataCenter, groupId, userId)
headers = {
    "x-api-token": apiToken,
    }

response = requests.delete(baseUrl, headers=headers)
print(response.text)

List Groups

The following example shows how to obtain a list of the group IDs and names of your groups.

# List Groups

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = 'YOUR DATACENTER'

baseUrl = "https://{0}.qualtrics.com/API/v3/groups".format(dataCenter)
headers = {
    "x-api-token": apiToken,
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

The following example shows the results from the List Groups API for a user who owns three groups:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "93e1f820-8e03-4ded-95af-146471a0e764"
    },
    "result": {
        "elements": [
            {
                "id": "GR_123",
                "name": "Group1"
            },
            {
                "id": "GR_456",
                "name": "Group2"
            },
            {
                "id": "GR_789",
                "name": "Group3"
            }
        ],
        "nextPage": null
    }
}

For results that include more than 100 groups, the nextPage member contains a URL containing the next 100 groups.

Get Group

The Get Group API allows you to obtain several pieces of information about a group:

The group's name
The group's creation date (see Dates and Times for format information)
The group's creator (a user ID)
The division ID this group belongs to
The group's ID
The group's type (as a group type ID)

Obtaining the Group ID

To use this API, you need to obtain the ID of the group you wish to query. To obtain the group ID, you should use the List Groups API to obtain a list of groups, their names, and IDs.

# Get Group

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

groupId = "GR_12345678"

baseUrl = "https://{0}.qualtrics.com/API/v3/groups/{1}".format(dataCenter, groupId)
headers = {
    "x-api-token": apiToken,
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

The following response gives an example of the object that is returned:

{
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "7843c825-f284-4121-ba0d-5e16fafa0409"
  },
  "result": {
    "autoMembership": "division",
    "creationDate": "2017-05-10T09:37:32Z",
    "creatorId": "UR_12334567890",
    "divisionId": "DV_1234567",
    "id": "GR_12345678",
    "name": "SW Users",
    "type": "GT_1234567890"
  }
}

The response object contains the following:

Member	Type	Description
autoMembership	String	Either "brand", "division", or "null". With "brand" or "division" all users in your organization or specified division will automatically be able to access this group's content. If "null", an administrator will need to manually add specific individuals to the group.
creationDate	String	The group's creation date and time as an ISO 8601 date. See Dates and Times for more information.
creatorId	String	The user ID of the user who created this group.
divisionId	String	The division ID this group belongs to.
id	String	The group's ID.
name	String	The group's name.
type	String	The group type ID of this group.

Update Group

You can change three properties of an existing group:

Group type
Division
Name

The following sample gives an existing group, identified by its group ID, a new name, "New Name".

# Update Group

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

groupId = "GR_123456789"

baseUrl = "https://{0}.qualtrics.com/API/v3/groups/{1}".format(dataCenter, groupId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = { 
  "name": "New Name",
   }
response = requests.put(baseUrl, json=data, headers=headers)
print(response.text)

Delete Group

The following example shows how to delete a group:

# Delete Group

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

groupId = "GR_1234567890"

baseUrl = "https://{0}.qualtrics.com/API/v3/groups/{1}".format(dataCenter, groupId)
headers = {
    "x-api-token": apiToken,
    }

response = requests.delete(baseUrl, headers=headers)
print(response.text)

Create Group​

Code and Qualtrics Support​

Add User to Group​

Remove User from Group​

List Groups​

Get Group​

Obtaining the Group ID​

Update Group​

Delete Group​