Group API

API Authentication

All URL endpoints should be utilized as part of a cURL authentication command. For more information, please review CommCare's API Authentication Documentation.

List Groups

URL: https://www.commcarehq.org/a/[domain]/api/[version]/group/

Input parameters:

Name	Description	Example
Format	Return data format (optional) Supported: json (default), xml	format=xml

Sample output:

{
  "meta": {
 	"limit": 20, 
	 "next": null, 
	 "offset": 0, 
	 "previous": null, 
	 "total_count": 3
 }, 
 "objects": [
 	{
    	 "case_sharing": false, 
		 "domain": "cloudcaredemo", 
		 "id": "1eb59d6938fc7e510254d8c2f63d944f", 
		 "metadata": {}, 
		 "name": "Wozzle", 
		 "path": [], 
		 "reporting": true, 
		 "users": ["91da6b1c78699adfb8679b741caf9f00", "8a642f722c9e617eeed29290e409fcd5"]
	 }, 
	 ...
   ]
}

Bulk API

URL: https://www.commcarehq.org/a/[domain]/api/[version]/group/

Supported Methods:

Method	Description
POST	Create group
PATCH	Create multiple groups

Input Parameters:

Name	Description	Example
name*	Group name	Wozzle
case_sharing	Whether users within this group will share cases with other members of this group	true/false (default=false)
reporting	Whether this group's name will appear in the group filter list for reports	true/false (default=true)
users	List of all users ids belonging to the group	(see examples) This is optional to specify.
metadata	Any additional custom data associated with the group	(see examples) This is optional to specify.

Output Parameters:

Name	Description	Example
id	Group UUID	3c5a623af057e23a32ae4000cf291339

Sample input:

Single Group:

JSON Input

{
 "case_sharing": false,
 "metadata": {
  "localization": "Ghana"
 },
 "name": "Wozzle",
 "reporting": true,
 "users": [
  "91da6b1c78699adfb8679b741caf9f00",
  "8a642f722c9e617eeed29290e409fcd5"
 ]
}

Multiple Groups (can include all other information from single group creation):

JSON Input

{
 "objects": [
  {
   "case_sharing": false, 
   "name": "Test 1", 
   "reporting": true
  },
  {
   "case_sharing": true, 
   "name": "Test 2", 
   "reporting": true
  }
 ]
}

Individual API

URL: https://www.commcarehq.org/a/[domain]/api/[version]/group/[group id]

Supported Methods:

Method	Description
GET	Get group
PUT	Edit group
DELETE	Delete group

Input Parameters:

Name	Description	Example
name	Group name	Wozzle
case_sharing	Whether users within this group will share cases with other members of this group	true/false
reporting	Whether this group's name will appear in the group filter list for reports	true/false
users	List of all users ids belonging to the group	(see examples) This will replace any existing users for the group.
metadata	Any additional custom data associated with the group	(see examples) This will replace any existing custom data for the group.

Sample input:

JSON Input

{
 "case_sharing": false,
 "metadata": {
  "localization": "Ghana"
 },
 "name": "Wozzle",
 "reporting": true,
 "users": [
  "91da6b1c78699adfb8679b741caf9f00",
  "8a642f722c9e617eeed29290e409fcd5"
 ]
}