Find groups

GET

/rest/api/3/groups/picker

Groups

Returns a list of groups whose names contain a query string. A list of group names can be provided to exclude groups from the results.

The primary use case for this resource is to populate a group picker suggestions list. To this end, the returned object includes the html field where the matched query term is highlighted in the group name with the HTML strong tag. Also, the groups list is wrapped in a response object that contains a header for use in the picker, specifically Showing X of Y matching groups.

The list returns with the groups sorted. If no groups match the list criteria, an empty list is returned.

This operation can be accessed anonymously.

Permissions required: Browse projects project permission. Anonymous calls and calls by users without the required permission return an empty list.

Browse users and groups global permission. Without this permission, calls where query is not an exact match to an existing group will return an empty list.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'http://jira.local:8080/jira/rest//rest/api/3/groups/picker'

Response Example

{
  "header": "Showing 20 of 25 matching groups",
  "total": 25,
  "groups": [
    {
      "name": "jdog-developers",
      "html": "<b>j</b>dog-developers",
      "groupId": "276f955c-63d7-42c8-9520-92d01dca0625"
    },
    {
      "name": "juvenal-bot",
      "html": "<b>j</b>uvenal-bot",
      "groupId": "6e87dc72-4f1f-421f-9382-2fee8b652487"
    }
  ]
}

Request

Query Params

accountId

string

optional

This parameter is deprecated, setting it does not affect the results. To find groups containing a particular user, use Get user groups.

query

string

optional

The string to find in group names.

exclude

array[string]

optional

As a group's name can change, use of excludeGroupIds is recommended to identify a group.
A group to exclude from the result. To exclude multiple groups, provide an ampersand-separated list. For example, exclude=group1&exclude=group2. This parameter cannot be used with the excludeGroupIds parameter.

excludeId

array[string]

optional

A group ID to exclude from the result. To exclude multiple groups, provide an ampersand-separated list. For example, excludeId=group1-id&excludeId=group2-id. This parameter cannot be used with the excludeGroups parameter.

maxResults

integer

optional

The maximum number of groups to return. The maximum number of groups that can be returned is limited by the system property jira.ajax.autocomplete.limit.

caseInsensitive

string

optional

Whether the search for groups should be case insensitive.

userName

string

optional

This parameter is no longer available. See the deprecation notice for details.

Responses

🟢200Returned if the request is successful.

application/json

Body

The list of groups found in a search, including header text (Showing X of Y matching groups) and total of matched groups.

groups

array[object (FoundGroup) {4}]

optional

groupId

string

optional

The ID of the group, which uniquely identifies the group across all Atlassian products. For example, 952d12c3-5b5b-4d04-bb32-44d383afc4b2.

html

string

optional

The group name with the matched query string highlighted with the HTML bold tag.

labels

array[object (GroupLabel) {3}]

optional

name

string

optional

The name of the group. The name of a group is mutable, to reliably identify a group use ``groupId.

header

string

optional

Header text indicating the number of groups in the response and the total number of groups found in the search.

total

integer <int32>

optional

The total number of groups found in the search.

Modified at 2023-07-13 03:27:27

Remove user from group

Find users and groups