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

Issue fields

Postman Collection
OpenAPI
GET

Get fields

Returns system and custom issue fields according to the following rules:

This operation can be accessed anonymously.

Permissions required: None.

Data Security Policy: Exempt from app access rules
Scopes
ClassicRECOMMENDED:read:jira-work
Granular:read:field:jira, read:avatar:jira, read:project-category:jira, read:project:jira, read:field-configuration:jira

Connect app scope requiredREAD

Request

This request has no parameters.

Responses

Returned if the request is successful.

application/json

array<FieldDetails>

GET/rest/api/3/field
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/field`, { 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 33 [ { "clauseNames": [ "description" ], "custom": false, "id": "description", "name": "Description", "navigable": true, "orderable": true, "schema": { "system": "description", "type": "string" }, "searchable": true }, { "clauseNames": [ "summary" ], "custom": false, "id": "summary", "key": "summary", "name": "Summary", "navigable": true, "orderable": true, "schema": { "system": "summary", "type": "string" }, "searchable": true } ]
POST

Create custom field

Creates a custom field.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes
ClassicRECOMMENDED:manage:jira-configuration
Granular:write:field:jira, read:avatar:jira, read:field:jira, read:project-category:jira, read:project:jira ...(Show more)

Connect app scope requiredADMIN

Request

Request bodyapplication/json

Definition of the custom field to be created

description

string

name

string

Required
searcherKey

string

type

string

Required

Responses

Returned if the custom field is created.

application/json

FieldDetails

Details about a field.

POST/rest/api/3/field
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/ import api, { route } from "@forge/api"; var bodyData = `{ "description": "Custom field for picking groups", "name": "New custom field", "searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher", "type": "com.atlassian.jira.plugin.system.customfieldtypes:grouppicker" }`; const response = await api.asUser().requestJira(route`/rest/api/3/field`, { 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 { "clauseNames": [ "cf[10101]", "New custom field" ], "custom": true, "id": "customfield_10101", "key": "customfield_10101", "name": "New custom field", "navigable": true, "orderable": true, "schema": { "custom": "com.atlassian.jira.plugin.system.customfieldtypes:project", "customId": 10101, "type": "project" }, "searchable": true, "untranslatedName": "New custom field" }
GET

Get fields paginated

Returns a paginated list of fields for Classic Jira projects. The list can include:

  • all fields
  • specific fields, by defining id
  • fields that contain a string in the field name or description, by defining query
  • specific fields that contain a string in the field name or description, by defining id and query

Use type must be set to custom to show custom fields only.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes
ClassicRECOMMENDED:read:jira-work
Granular:read:field:jira, read:field-configuration:jira

Connect app scope requiredNONE

Request

Query parameters

startAt

integer

maxResults

integer

type

array<string>

id

array<string>

query

string

orderBy

string

expand

string

Responses

Returned if the request is successful.

application/json

PageBeanField

A page of items.

GET/rest/api/3/field/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/field/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 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 { "isLast": false, "maxResults": 50, "startAt": 0, "total": 2, "values": [ { "id": "customfield_10000", "name": "Approvers", "schema": { "custom": "com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker", "customId": 10000, "items": "user", "type": "array" }, "description": "Contains users needed for approval. This custom field was created by Jira Service Desk.", "key": "customfield_10000", "stableId": "sfid:approvers", "isLocked": true, "searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:userpickergroupsearcher", "screensCount": 2, "contextsCount": 2, "lastUsed": { "type": "TRACKED", "value": "2021-01-28T07:37:40.000+0000" } }, { "id": "customfield_10001", "name": "Change reason", "schema": { "custom": "com.atlassian.jira.plugin.system.customfieldtypes:select", "customId": 10001, "type": "option" }, "description": "Choose the reason for the change request", "key": "customfield_10001", "stableId": "sfid:change-reason", "isLocked": false, "searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:multiselectsearcher", "screensCount": 2, "contextsCount": 2, "projectsCount": 2, "lastUsed": { "type": "NOT_TRACKED" } } ] }
GET

Get fields in trash paginated

Returns a paginated list of fields in the trash. The list may be restricted to fields whose field name or description partially match a string.

Only custom fields can be queried, type must be set to custom.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes
ClassicRECOMMENDED:read:jira-work
Granular:read:field:jira, read:field-configuration:jira, read:user:jira

Connect app scope requiredREAD

Request

Query parameters

startAt

integer

maxResults

integer

id

array<string>

query

string

expand

string

orderBy

string

Responses

Returned if the request is successful.

application/json

PageBeanField

A page of items.

GET/rest/api/3/field/search/trashed
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/field/search/trashed`, { 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 33 34 35 { "isLast": false, "maxResults": 50, "startAt": 0, "total": 1, "values": [ { "id": "customfield_10000", "name": "Approvers", "schema": { "custom": "com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker", "customId": 10003, "type": "array" }, "description": "Contains users needed for approval. This custom field was created by Jira Service Desk.", "key": "customfield_10003", "trashedDate": "2022-10-06T07:32:47.000+0000", "trashedBy": { "accountId": "5b10a2844c20165700ede21g", "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" }, "plannedDeletionDate": "2022-10-24T07:32:47.000+0000" } ] }
PUT

Update custom field

Updates a custom field.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes
ClassicRECOMMENDED:manage:jira-configuration
Granular:write:field:jira

Connect app scope requiredADMIN

Request

Path parameters

fieldId

string

Required

Request bodyapplication/json

The custom field update details.

description

string

name

string

searcherKey

string

Responses

Returned if the request is successful.

application/json

any

PUT/rest/api/3/field/{fieldId}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "description": "Select the manager and the corresponding employee.", "name": "Managers and employees list", "searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:cascadingselectsearcher" }`; const response = await api.asUser().requestJira(route`/rest/api/3/field/{fieldId}`, { method: 'PUT', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
GET

Get contexts for a fieldDeprecated

Returns a paginated list of the contexts a field is used in. Deprecated, use Get custom field contexts.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes
ClassicRECOMMENDED:manage:jira-project
Granular:read:field:jira, read:avatar:jira, read:project-category:jira, read:project:jira

Connect app scope requiredNONE

Request

Path parameters

fieldId

string

Required

Query parameters

startAt

integer

maxResults

integer

Responses

Returned if the request is successful.

application/json

PageBeanContext

A page of items.

GET/rest/api/3/field/{fieldId}/contexts
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/field/{fieldId}/contexts`, { 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 { "isLast": false, "maxResults": 1, "startAt": 0, "total": 5, "values": [ { "id": 10001, "name": "Default Context" } ] }
DEL

Delete custom field

Deletes a custom field. The custom field is deleted whether it is in the trash or not. See Edit or delete a custom field for more information on trashing and deleting custom fields.

This operation is asynchronous. Follow the location link in the response to determine the status of the task and use Get task to obtain subsequent updates.

Permissions required: Administer Jira global permission.

Data Security Policy: Not exempt from app access rules
Scopes
ClassicRECOMMENDED:manage:jira-configuration
Granular:delete:field:jira

Connect app scope requiredADMIN

Request

Path parameters

id

string

Required

Responses

Returned if the request is successful.

application/json

TaskProgressBeanObject

Details about a task.

DEL/rest/api/3/field/{id}
1 2 3 4 5 6 7 8 9 10 // 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/field/{id}`, { method: 'DELETE' }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.text());
303Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "description": "<string>", "elapsedRuntime": 48, "finished": 49, "id": "<string>", "lastUpdate": 62, "message": "<string>", "progress": 51, "self": "<string>", "started": 48, "status": "ENQUEUED", "submitted": 50, "submittedBy": 42 }
POST

Restore custom field from trash

Restores a custom field from trash. See Edit or delete a custom field for more information on trashing and deleting custom fields.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes
ClassicRECOMMENDED:manage:jira-configuration
Granular:write:field:jira

Connect app scope requiredADMIN

Request

Path parameters

id

string

Required

Responses

Returned if the request is successful.

application/json

any

POST/rest/api/3/field/{id}/restore
1 2 3 4 5 6 7 8 9 10 11 12 13 // 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/field/{id}/restore`, { method: 'POST', headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
POST

Move custom field to trash

Moves a custom field to trash. See Edit or delete a custom field for more information on trashing and deleting custom fields.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes
ClassicRECOMMENDED:manage:jira-configuration
Granular:delete:field:jira

Connect app scope requiredADMIN

Request

Path parameters

id

string

Required

Responses

Returned if the request is successful.

application/json

any

POST/rest/api/3/field/{id}/trash
1 2 3 4 5 6 7 8 9 10 11 12 13 // 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/field/{id}/trash`, { method: 'POST', headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());

Rate this page: