Find users and groups

GET

/rest/api/3/groupuserpicker

Group and user picker

Returns a list of users and groups matching a string. The string is used:

for users, to find a case-insensitive match with display name and e-mail address. Note that if a user has hidden their email address in their user profile, partial matches of the email address will not find the user. An exact match is required.

for groups, to find a case-sensitive match with group name.

For example, if the string tin is used, records with the display name Tina, email address sarah@tinplatetraining.com, and the group accounting would be returned.

Optionally, the search can be refined to:

the projects and issue types associated with a custom field, such as a user picker. The search can then be further refined to return only users and groups that have permission to view specific:

projects.

issue types.

If multiple projects or issue types are specified, they must be a subset of those enabled for the custom field or no results are returned. For example, if a field is enabled for projects A, B, and C then the search could be limited to projects B and C. However, if the search is limited to projects B and D, nothing is returned.

not return Connect app users and groups.

return groups that have a case-insensitive match with the query.

The primary use case for this resource is to populate a picker field suggestion list with users or groups. To this end, the returned object includes an html field for each list. This field highlights the matched query term in the item name with the HTML strong tag. Also, each list is wrapped in a response object that contains a header for use in a picker, specifically Showing X of Y matching groups.

This operation can be accessed anonymously.

Permissions required: Browse users and groups global permission.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'http://jira.local:8080/jira/rest//rest/api/3/groupuserpicker?query='

Response Example

200 - Success

{
  "users": {
    "users": [
      {
        "accountId": "5b10a2844c20165700ede21g",
        "accountType": "atlassian",
        "name": "mia",
        "key": "mia",
        "html": "<strong>Mi</strong>a Krystof - <strong>mi</strong>a@example.com (<strong>mi</strong>a)",
        "displayName": "Mia Krystof",
        "avatarUrl": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16"
      }
    ],
    "total": 25,
    "header": "Showing 20 of 25 matching groups"
  },
  "groups": {
    "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

query

string

required

The search string.

maxResults

integer

optional

The maximum number of items to return in each list.

showAvatar

string

optional

Whether the user avatar should be returned. If an invalid value is provided, the default value is used.

fieldId

string

optional

The custom field ID of the field this request is for.

projectId

array[string]

optional

The ID of a project that returned users and groups must have permission to view. To include multiple projects, provide an ampersand-separated list. For example, projectId=10000&projectId=10001. This parameter is only used when fieldId is present.

issueTypeId

array[string]

optional

The ID of an issue type that returned users and groups must have permission to view. To include multiple issue types, provide an ampersand-separated list. For example, issueTypeId=10000&issueTypeId=10001. Special values, such as -1 (all standard issue types) and -2 (all subtask issue types), are supported. This parameter is only used when fieldId is present.

avatarSize

string

optional

The size of the avatar to return. If an invalid value is provided, the default value is used.

caseInsensitive

string

optional

Whether the search for groups should be case insensitive.

excludeConnectAddons

string

optional

Whether Connect app users and groups should be excluded from the search results. If an invalid value is provided, the default value is used.

Responses

🟢200Returned if the request is successful.

application/json

Body

List of users and groups found in a search.

groups

object (FoundGroups)

optional

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

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.

users

object (FoundUsers)

optional

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

header

string

optional

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

total

integer <int32>

optional

The total number of users found in the search.

users

array[object (UserPickerUser) {6}]

optional

🟠400Returned if the query parameter is not provided.

🟠401Returned if the authentication credentials are incorrect or missing.

🟠403Returned if the user does not have the necessary permission.

🟠429Returned if the rate limit is exceeded. User search endpoints share a collective rate limit for the tenant, in addition to Jira's normal rate limiting you may receive a rate limit for user search. Please respect the Retry-After header.

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

Find groups

Get license