---
title: "Find users and groups"
method: GET
path: "/rest/api/3/groupuserpicker"
tags: ["Group and user picker"]
---

# Find users and groups

`GET /rest/api/3/groupuserpicker`

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](#permissions) required:** *Browse users and groups* [global permission](https://confluence.atlassian.com/x/yodKLg).

## Query parameters

- `query` string, required
- `maxResults` integer
- `showAvatar` boolean
- `fieldId` string
- `projectId` string[]
- `issueTypeId` string[]
- `avatarSize` 'xsmall' | 'xsmall@2x' | 'xsmall@3x' | 'small' | 'small@2x' | 'small@3x' | 'medium' | 'medium@2x' | 'medium@3x' | 'large' | 'large@2x' | 'large@3x' | 'xlarge' | 'xlarge@2x' | 'xlarge@3x' | 'xxlarge' | 'xxlarge@2x' | 'xxlarge@3x' | 'xxxlarge' | 'xxxlarge@2x' | 'xxxlarge@3x'
- `caseInsensitive` boolean
- `excludeConnectAddons` boolean
- `includeAiAgents` boolean

## Response `200`

Returned if the request is successful.

- FoundUsersAndGroups — List of users and groups found in a search.
  - `groups` FoundGroups — The list of groups found in a search, including header text (Showing X of Y matching groups) and total of matched groups.
    - `groups` FoundGroup[]
      - `avatarUrl` string — Avatar url for the group/team if present.
      - `groupId` string — The ID of the group, which uniquely identifies the group across all Atlassian products. For example, *952d12c3-5b5b-4d04-bb32-44d383afc4b2*.
      - `html` string — The group name with the matched query string highlighted with the HTML bold tag.
      - `labels` GroupLabel[]
        - `text` string — The group label name.
        - `title` string — The title of the group label.
        - `type` 'ADMIN' | 'SINGLE' | 'MULTIPLE' — The type of the group label.
      - `managedBy` 'EXTERNAL' | 'ADMINS' | 'TEAM_MEMBERS' | 'OPEN' — Describes who/how the team is managed. The possible values are \* external - when team is synced from an external directory like SCIM or HRIS, and team members cannot be modified. \* admins - when a team is managed by an admin (team members can only be modified by admins). \* team-members - managed by existing team members, new members need to be invited to join. \* open - anyone can join or modify this team.
      - `name` string — The name of the group. The name of a group is mutable, to reliably identify a group use ``groupId`.`
      - `usageType` 'USERBASE_GROUP' | 'TEAM_COLLABORATION' | 'ADMIN_OVERSIGHT' — Describes the type of group. The possible values are \* team-collaboration - A platform team managed in people directory. \* userbase-group - a group of users created in adminhub. \* admin-oversight - currently unused.
    - `header` string — Header text indicating the number of groups in the response and the total number of groups found in the search.
    - `total` integer — The total number of groups found in the search.
  - `users` FoundUsers — The list of users found in a search, including header text (Showing X of Y matching users) and total of matched users.
    - `header` string — Header text indicating the number of users in the response and the total number of users found in the search.
    - `total` integer — The total number of users found in the search.
    - `users` UserPickerUser[]
      - `accountId` string — The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*.
      - `accountType` 'atlassian' | 'app' | 'customer' | 'unknown' — The user account type. Can take the following values: * `atlassian` regular Atlassian user account * `app` system account used for Connect applications and OAuth to represent external systems * `customer` Jira Service Desk account representing an external service desk
      - `avatarUrl` string, uri — The avatar URL of the user.
      - `displayName` string — The display name of the user. Depending on the user’s privacy setting, this may be returned as null.
      - `html` string — The display name, email address, and key of the user with the matched query string highlighted with the HTML bold tag.
      - `key` string — This property is no longer available. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details.
      - `name` string — This property is no longer available . See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details.

## Other responses

- `400` — Returned if the query parameter is not provided.
- `401` — Returned if the authentication credentials are incorrect or missing.
- `403` — Returned if the user does not have the necessary permission.
- `429` — Returned 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.

---

[API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api-2/versions/5a51740d7ab3/schema)