Skip to main content

Create Group

Endpoint​

/i/groups/create

Ⓔ Enterprise Only
This API is available exclusively in Countly Enterprise.

Overview​

Creates a new group definition and optionally assigns users.

Authentication​

  • Authentication methods:
    • API Key (parameter): api_key=YOUR_API_KEY
    • Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
    • Auth Token (header): countly-token: YOUR_AUTH_TOKEN

Permissions​

  • Required access: global admin

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or auth_token)API key authentication
auth_tokenStringYes (or api_key)Auth token authentication
argsObject (JSON string)YesStringified group object

args Object Fields​

FieldTypeRequiredDescription
nameStringYesGroup display name
groupIDStringYesUnique group identifier
global_adminBooleanYesGlobal admin flag for group members
usersArrayNoUser IDs to assign during creation
admin_ofArrayNoBackward-compatible app admin mapping input
user_ofArrayNoBackward-compatible app user mapping input
permissionObjectNoGroup permission object

Response​

Success Response​

{
  "result": {
    "status": "Success",
    "group": {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Marketing Team",
      "groupID": "marketing-team",
      "global_admin": false,
      "permission": {
        "_": { "u": [], "a": [] },
        "c": {},
        "r": {},
        "u": {},
        "d": {}
      }
    }
  }
}

Response Fields​

FieldTypeDescription
resultObjectCreate operation result
result.statusStringAlways Success when created
result.groupObjectCreated group payload
result.group._idStringNew group ID

Error Responses​

HTTP StatusResponse
200{ "result": "Not enough args" }
200{ "result": "groups.error-unique-group-id" }
400{ "result": "Missing parameter \"api_key\" or \"auth_token\"" }
400Error object from create path

Behavior/Processing​

  1. Validates required fields in args.
  2. Validates unique groupID.
  3. Creates group in countly.groups.
  4. If users is provided, updates matched users and synchronizes group membership fields.

Database Collections​

CollectionUsed forData touched by this endpoint
countly.groupsEndpoint data source** - Stores created group record
countly.membersEndpoint data source** - Updated when users are passed in create request

Examples​

Example 1: Create Group​

Endpoint form:

https://your-server.com/i/groups/create?api_key=YOUR_API_KEY&args={"name":"Marketing Team","groupID":"marketing-team","global_admin":false,"permission":{"_":{"u":[],"a":[]},"c":{},"r":{},"u":{},"d":{}}}

Decoded args object:

{
  "name": "Marketing Team",
  "groupID": "marketing-team",
  "global_admin": false,
  "permission": {
    "_": { "u": [], "a": [] },
    "c": {},
    "r": {},
    "u": {},
    "d": {}
  }
}

Example 2: Create Group with Initial Users​

Endpoint form:

https://your-server.com/i/groups/create?api_key=YOUR_API_KEY&args={"name":"Support Team","groupID":"support-team","global_admin":false,"users":["507f191e810c19729de860ea","507f191e810c19729de860eb"]}

Ⓔ Enterprise​

This feature is part of Countly Enterprise.

Get Access:

Already a Customer? Use support portal if you have any questions

Last Updated​

2026-02-16