Cloud

Jira Cloud platform / Reference / REST API v3

Group and user picker

This resource represents a list of users and a list of groups. Use it to obtain the details to populate user and group picker suggestions list.

Operations

GET/rest/api/3/groupuserpicker

GET

Find users and groups

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.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:group:jira, read:user:jira

Connect app scope required: READ

Request

Query parameters

query

string

Required

maxResults

integer

showAvatar

boolean

fieldId

string

projectId

array<string>

issueTypeId

array<string>

avatarSize

string

caseInsensitive

boolean

excludeConnectAddons

boolean

Responses

Returned if the request is successful.

application/json

FoundUsersAndGroups

List of users and groups found in a search.

GET/rest/api/3/groupuserpicker

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/groupuserpicker?query={query}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "groups": {
    "groups": [
      {
        "groupId": "276f955c-63d7-42c8-9520-92d01dca0625",
        "html": "<b>j</b>dog-developers",
        "name": "jdog-developers"
      },
      {
        "groupId": "6e87dc72-4f1f-421f-9382-2fee8b652487",
        "html": "<b>j</b>uvenal-bot",
        "name": "juvenal-bot"
      }
    ],
    "header": "Showing 20 of 25 matching groups",
    "total": 25
  },
  "users": {
    "header": "Showing 20 of 25 matching groups",
    "total": 25,
    "users": [
      {
        "accountId": "5b10a2844c20165700ede21g",
        "accountType": "atlassian",
        "avatarUrl": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
        "displayName": "Mia Krystof",
        "html": "<strong>Mi</strong>a Krystof - <strong>mi</strong>a@example.com (<strong>mi</strong>a)",
        "key": "mia",
        "name": "mia"
      }
    ]
  }
}