Skip to main content

Groups API

Everything you need for top-level group management

Anthony Karcz avatar
Written by Anthony Karcz
Updated over 4 years ago

What This API Endpoint Does

With the Groups API you create or delete a group and update a group's name. Admins see these changes reflected on the People tab. You also use this endpoint to retrieve a list of groups or details of a specific group.

Endpoints

  • POST /groups - create a new group

  • GET /groups - list groups

  • GET /groups/{groupId} - get details of a group by group id

  • PUT /groups/{groupId} - update a group by group id

  • DELETE /groups/{groupId} - delete a group by group id

Group object

  • id (string) - the unique identifier of the group

  • isManagedByIdentityProvider (boolean) - Returns true if the group is an SSO managed group, otherwise false

  • membersUrl (string) - URL to list group's members from the API

  • reportersUrl (string) - URL to list reporters for group from the API

  • name (string) - the name of the group

  • url (string) - URL to fetch the group's details from the API

Create Group

POST /groups

Request Parameters (JSON)

  • name (string, required) - the name of the group

Example Response

{ 
 "id": "example-group-id", 
 "isManagedByIdentityProvider": false, 
 "membersUrl": "https://api.rise.com/groups/example-group-id/users",
 "reportersUrl": "https://api.rise.com/groups/example-group-id/reporters",
 "name": "Example Group",
 "url": "https://api.rise.com/groups/example-group-id" 
}

Endpoint-specific Error Codes

  • code: 'duplicate_name' - cannot create group because a group with the specified name already exists

List Groups

GET /groups

Request Parameters (Query String)

  • limit (integer, optional) - the maximum number of results to return in a single response (see Pagination); must be between 1 and 100 (defaults to 50)

  • name (string, optional) - Return groups with the specified name.

Example Response

{ 
 "groups": [ 
   { 
    "id": "example-group-id-1", 
    "isManagedByIdentityProvider": false,
    "membersUrl": "https://api.rise.com/groups/example-group-id/users",
    "reportersUrl": "https://api.rise.com/groups/example-group-id/reporters",
    "name": "Example Group" 
    "url": "https://api.rise.com/groups/example-group-id-1"
   }, ... 
 ], 
 "nextUrl": "https://url-for-next-page-of-results" 
}

Retrieve Group by ID

GET /groups/{groupId}

Example Response

{ 
  "id": "example-group-id", 
  "isManagedByIdentityProvider": false,
  "membersUrl": "https://api.rise.com/groups/example-group-id/users",
  "reportersUrl": "https://api.rise.com/groups/example-group-id/reporters",
  "name": "Example Group" 
  "url": "https://api.rise.com/groups/example-group-id"
}

Endpoint-specific Error Codes

  • group_not_found - cannot retrieve group because group does not exist

Update Group by ID

PUT /groups/{groupId}

Request Parameters (JSON)

  • name (string, required) - the name of the group

Success Response

204 "No Content"

Endpoint-specific error codes:

  • group_not_found - cannot update group because group does not exist

  • read_only_group - cannot make changes to the specified group (Example: you cannot modify the "Everyone" group)

  • sso_group - the group you have specified is an SSO provisioned group and cannot be modified.

Delete Group by ID

DELETE /groups/{groupId}

Success Response

204 "No Content"

Endpoint-specific error codes:

  • group_not_found - cannot delete group because group does not exist

  • read_only_group - cannot delete the specified group (Example: you cannot modify the "Everyone" group)

  • sso_group - the group you have specified is an SSO provisioned group and cannot be deleted.

Did this answer your question?