• Announcement banner
  • App data policies (EAP)
  • Application roles
  • Audit records
  • Avatars
  • Classification levels
  • Dashboards
  • Filters
  • Filter sharing
  • Group and user picker
  • Groups
  • Issues
  • UI modifications (apps)
  • Issue attachments
  • Issue comments
  • Issue comment properties
  • Issue fields
  • Issue field configurations
  • Issue custom field contexts
  • Issue custom field options
  • Issue custom field options (apps)
  • Issue custom field values (apps)
  • Issue custom field configuration (apps)
  • Issue navigator settings
  • Issue notification schemes
  • Issue priorities
  • Issue properties
  • Issue resolutions
  • Issue security level
  • Issue security schemes
  • Issue types
  • Issue type schemes
  • Issue type screen schemes
  • Issue type properties
  • Issue votes
  • Issue watchers
  • Issue worklogs
  • Issue worklog properties
  • Jira expressions
  • Jira settings
  • JQL
  • JQL functions (apps)
  • Labels
  • License metrics
  • Myself
  • Permissions
  • Permission schemes
  • Projects
  • Project avatars
  • Project categories
  • Project classification levels
  • Project components
  • Project email
  • Project features
  • Project key and name validation
  • Project permission schemes
  • Project properties
  • Project roles
  • Project role actors
  • Project types
  • Project versions
  • Screens
  • Screen tabs
  • Screen tab fields
  • Screen schemes
  • Server info
  • Status
  • Tasks
  • Time tracking
  • Users
  • User properties
  • Webhooks
  • Workflows
  • Workflow transition rules
  • Workflow schemes
  • Workflow scheme project associations
  • Workflow scheme drafts
  • Workflow statuses
  • Workflow status categories
  • Workflow transition properties
  • App properties
  • Dynamic modules
  • App migration
  • Service Registry
Cloud
Jira Cloud platform / Reference / REST API v3 (beta)

Users

Postman Collection
OpenAPI

This resource represent users. Use it to:

  • get, get a list of, create, and delete users.
  • get, set, and reset a user's default issue table columns.
  • get a list of the groups the user belongs to.
  • get a list of user account IDs for a list of usernames or user keys.
GET

Get user

Returns a user.

Privacy controls are applied to the response based on the user's preferences. This could mean, for example, that the user's email address is hidden. See the Profile visibility overview for more details.

Permissions required: Browse users and groups global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-user
Granular:read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira

Request

Query parameters

accountId

string

username

string

key

string

expand

string

Responses

Returned if the request is successful.

application/json

User

A user with details as permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:

  • User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, displayName provides an indication and other parameters have default values or are blank (for example, email is blank).
  • User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, accountId returns unknown and all other parameters have fallback values.
  • User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values.
GET/rest/api/3/user
1 2 3 4 5 6 7 8 9 10 11 12 // 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/user?accountId=5b10ac8d82e05b22cc7d4ef5`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "active": true, "applicationRoles": { "items": [], "size": 1 }, "avatarUrls": { "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32", "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48" }, "displayName": "Mia Krystof", "emailAddress": "mia@example.com", "groups": { "items": [], "size": 3 }, "key": "", "name": "", "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "timeZone": "Australia/Sydney" }
POST

Create userExperimental

Creates a user. This resource is retained for legacy compatibility. As soon as a more suitable alternative is available this resource will be deprecated.

If the user exists and has access to Jira, the operation returns a 201 status. If the user exists but does not have access to Jira, the operation returns a 400 status.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

Request

Request bodyapplication/json

Details about the user to be created.

applicationKeys

array<string>

displayName

string

emailAddress

string

Required
key

string

name

string

password

string

products

array<string>

Additional Properties

any

Responses

Returned if the request is successful.

application/json

User

A user with details as permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:

  • User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, displayName provides an indication and other parameters have default values or are blank (for example, email is blank).
  • User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, accountId returns unknown and all other parameters have fallback values.
  • User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values.
POST/rest/api/3/user
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ // // This API resource doesn't support Oauth2 (3LO). See alternate authorization methods: // https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication import api, { route } from "@forge/api"; var bodyData = `{ "emailAddress": "mia@atlassian.com" }`; const response = await api.requestJira(route`/rest/api/3/user`, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
201Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "active": true, "applicationRoles": { "items": [], "size": 1 }, "avatarUrls": { "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32", "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48" }, "displayName": "Mia Krystof", "emailAddress": "mia@example.com", "groups": { "items": [], "size": 3 }, "key": "", "name": "", "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "timeZone": "Australia/Sydney" }
DEL

Delete userExperimental

Deletes a user. If the operation completes successfully then the user is removed from Jira's user base. This operation does not delete the user's Atlassian account.

Permissions required: Site administration (that is, membership of the site-admin group).

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

Request

Query parameters

accountId

string

Required
username

string

key

string

Responses

Returned if the request is successful.

DEL/rest/api/3/user
1 2 3 4 5 6 7 8 9 10 11 12 13 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ // // This API resource doesn't support Oauth2 (3LO). See alternate authorization methods: // https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication import api, { route } from "@forge/api"; const response = await api.requestJira(route`/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4ef5`, { method: 'DELETE' }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.text());
GET

Bulk get usersExperimental

Returns a paginated list of the users specified by one or more account IDs.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-user
Granular:read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira

Request

Query parameters

startAt

integer

maxResults

integer

username

array<string>

key

array<string>

accountId

array<string>

Required

Responses

Returned if the request is successful.

application/json

PageBeanUser

A page of items.

GET/rest/api/3/user/bulk
1 2 3 4 5 6 7 8 9 10 11 12 // 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/user/bulk?accountId={accountId}`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "isLast": true, "maxResults": 100, "startAt": 0, "total": 1, "values": [ { "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "active": true, "avatarUrls": { "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32", "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48" }, "displayName": "Mia Krystof", "emailAddress": "mia@example.com", "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "timeZone": "Australia/Sydney" } ] }
GET

Get account IDs for usersExperimental

Returns the account IDs for the users specified in the key or username parameters. Note that multiple key or username parameters can be specified.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-user
Granular:read:user:jira

Request

Query parameters

startAt

integer

maxResults

integer

username

array<string>

key

array<string>

Responses

Returned if the request is successful.

application/json

array<UserMigrationBean>

GET/rest/api/3/user/bulk/migration
1 2 3 4 5 6 7 8 9 10 11 12 // 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/user/bulk/migration`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 [ { "username": "mia", "accountId": "5b10a2844c20165700ede21g" }, { "username": "emma", "accountId": "5b10ac8d82e05b22cc7d4ef5" } ]
GET

Get user default columns

Returns the default issue table columns for the user. If accountId is not passed in the request, the calling user's details are returned.

Permissions required:

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-user
Granular:read:user.columns:jira, read:filter.column:jira

Request

Query parameters

accountId

string

username

string

Responses

Returned if the request is successful.

application/json

array<ColumnItem>

GET/rest/api/3/user/columns
1 2 3 4 5 6 7 8 9 10 11 12 // 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/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 [ { "label": "<string>", "value": "<string>" } ]
PUT

Set user default columns

Sets the default issue table columns for the user. If an account ID is not passed, the calling user's default columns are set. If no column details are sent, then all default columns are removed.

The parameters for this resource are expressed as HTML form data. For example, in curl:

curl -X PUT -d columns=summary -d columns=description https://your-domain.atlassian.net/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5'

Permissions required:

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

Request

Query parameters

accountId

string

Request body*/* multipart/form-data

The ID of a column to set. To set multiple columns, send multiple columns parameters.

columns

array<string>

Responses

Returned if the request is successful.

application/json

any

PUT/rest/api/3/user/columns
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ // // This API resource doesn't support Oauth2 (3LO). See alternate authorization methods: // https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication import api, { route } from "@forge/api"; const response = await api.requestJira(route`/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5`, { method: 'PUT', headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
DEL

Reset user default columns

Resets the default issue table columns for the user to the system default. If accountId is not passed, the calling user's default columns are reset.

Permissions required:

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

Request

Query parameters

accountId

string

username

string

Responses

Returned if the request is successful.

DEL/rest/api/3/user/columns
1 2 3 4 5 6 7 8 9 10 11 12 13 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ // // This API resource doesn't support Oauth2 (3LO). See alternate authorization methods: // https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication import api, { route } from "@forge/api"; const response = await api.requestJira(route`/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5`, { method: 'DELETE' }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.text());
GET

Get user email

Returns a user's email address. This API is only available to apps approved by Atlassian, according to these guidelines.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredACCESS_EMAIL_ADDRESSES

Request

Query parameters

accountId

string

Required

Responses

Returned if the request is successful.

application/json

UnrestrictedUserEmail
GET/rest/api/3/user/email
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ // // This API resource doesn't support Oauth2 (3LO). See alternate authorization methods: // https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication import api, { route } from "@forge/api"; const response = await api.requestJira(route`/rest/api/3/user/email?accountId={accountId}`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 { "accountId": "<string>", "email": "<string>" }
GET

Get user email bulk

Returns a user's email address. This API is only available to apps approved by Atlassian, according to these guidelines.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredACCESS_EMAIL_ADDRESSES

Request

Query parameters

accountId

array<string>

Required

Responses

Returned if the request is successful.

application/json

UnrestrictedUserEmail
GET/rest/api/3/user/email/bulk
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ // // This API resource doesn't support Oauth2 (3LO). See alternate authorization methods: // https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication import api, { route } from "@forge/api"; const response = await api.requestJira(route`/rest/api/3/user/email/bulk?accountId={accountId}`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 { "accountId": "<string>", "email": "<string>" }
GET

Get user groups

Returns the groups to which a user belongs.

Permissions required: Browse users and groups global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-user
Granular:read:group:jira

Request

Query parameters

accountId

string

Required
username

string

key

string

Responses

Returned if the request is successful.

application/json

array<GroupName>

GET/rest/api/3/user/groups
1 2 3 4 5 6 7 8 9 10 11 12 // 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/user/groups?accountId=5b10ac8d82e05b22cc7d4ef5`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 { "groupId": "276f955c-63d7-42c8-9520-92d01dca0625", "name": "jira-administrators", "self": "https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625" }
GET

Get all users default

Returns a list of all users, including active users, inactive users and previously deleted users that have an Atlassian account.

Privacy controls are applied to the response based on the users' preferences. This could mean, for example, that the user's email address is hidden. See the Profile visibility overview for more details.

Permissions required: Browse users and groups global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

ClassicRECOMMENDED:read:jira-user
Granular:read:user:jira, read:application-role:jira, read:avatar:jira, read:group:jira

Request

Query parameters

startAt

integer

maxResults

integer

Responses

Returned if the request is successful.

application/json

array<User>

GET/rest/api/3/users
1 2 3 4 5 6 7 8 9 10 11 12 // 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/users`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 [ { "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "active": false, "avatarUrls": { "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32", "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48" }, "displayName": "Mia Krystof", "key": "", "name": "", "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g" }, { "accountId": "5b10ac8d82e05b22cc7d4ef5", "accountType": "atlassian", "active": false, "avatarUrls": { "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=16&s=16", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=24&s=24", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=32&s=32", "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=48&s=48" }, "displayName": "Emma Richards", "key": "", "name": "", "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4ef5" } ]
GET

Get all users

Returns a list of all users, including active users, inactive users and previously deleted users that have an Atlassian account.

Privacy controls are applied to the response based on the users' preferences. This could mean, for example, that the user's email address is hidden. See the Profile visibility overview for more details.

Permissions required: Browse users and groups global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

ClassicRECOMMENDED:read:jira-user
Granular:read:user:jira, read:application-role:jira, read:avatar:jira, read:group:jira

Request

Query parameters

startAt

integer

maxResults

integer

Responses

Returned if the request is successful.

application/json

array<User>

GET/rest/api/3/users/search
1 2 3 4 5 6 7 8 9 10 11 12 // 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/users/search`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 [ { "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "active": false, "avatarUrls": { "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32", "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48" }, "displayName": "Mia Krystof", "key": "", "name": "", "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g" }, { "accountId": "5b10ac8d82e05b22cc7d4ef5", "accountType": "atlassian", "active": false, "avatarUrls": { "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=16&s=16", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=24&s=24", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=32&s=32", "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=48&s=48" }, "displayName": "Emma Richards", "key": "", "name": "", "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4ef5" } ]

Rate this page: