• 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 v2

Issue custom field options (apps)

Postman Collection
OpenAPI

This resource represents custom issue field select list options created by a Connect app. See Issue custom field options to manipulate options created in Jira or using the REST API.

A select list issue field is a type of issue field that enables a user to select an option from a list. Use it to add, remove, and update the options of a select list issue field.

GET

Get all issue field options

Returns a paginated list of all the options of a select list issue field. A select list issue field is a type of issue field that enables a user to select a value from a list of options.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredNONE

ClassicRECOMMENDED:manage:jira-configuration
Granular:read:field.option:jira

Request

Path parameters

fieldKey

string

Required

Query parameters

startAt

integer

maxResults

integer

Responses

Returned if the request is successful.

application/json

PageBeanIssueFieldOption

A page of items.

GET/rest/api/2/field/{fieldKey}/option
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/2/field/{fieldKey}/option`, { 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 { "isLast": false, "maxResults": 1, "nextPage": "https://your-domain.atlassian.net/rest/api/2/field/fieldKey/option?startAt=1&maxResults=1", "self": "https://your-domain.atlassian.net/rest/api/2/field/fieldKey/option?startAt=0&maxResults=1", "startAt": 0, "total": 10, "values": [ { "id": 1, "value": "Team 1", "properties": { "leader": { "name": "Leader Name", "email": "lname@example.com" }, "members": 42, "description": "The team's description", "founded": "2016-06-06" }, "config": { "scope": { "projects": [], "projects2": [ { "id": 1001, "attributes": [ "notSelectable" ] }, { "id": 1002, "attributes": [ "notSelectable" ] } ], "global": {} }, "attributes": [] } } ] }
POST

Create issue field option

Creates an option for a select list issue field.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Each field can have a maximum of 10000 options, and each option can have a maximum of 10000 scopes.

Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredNONE

ClassicRECOMMENDED:manage:jira-configuration
Granular:write:field.option:jira

Request

Path parameters

fieldKey

string

Required

Request bodyapplication/json

config

IssueFieldOptionConfiguration

properties

object

value

string

Required
Additional Properties

any

Responses

Returned if the request is successful.

application/json

IssueFieldOption

Details of the options for a select list issue field.

POST/rest/api/2/field/{fieldKey}/option
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 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "config": { "attributes": [], "scope": { "global": {}, "projects": [], "projects2": [ { "attributes": [ "notSelectable" ], "id": 1001 }, { "attributes": [ "notSelectable" ], "id": 1002 } ] } }, "properties": { "description": "The team's description", "founded": "2016-06-06", "leader": { "email": "lname@example.com", "name": "Leader Name" }, "members": 42 }, "value": "Team 1" }`; const response = await api.asUser().requestJira(route`/rest/api/2/field/{fieldKey}/option`, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); 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 { "id": 1, "value": "Team 1", "properties": { "leader": { "name": "Leader Name", "email": "lname@example.com" }, "members": 42, "description": "The team's description", "founded": "2016-06-06" }, "config": { "scope": { "projects": [], "projects2": [ { "id": 1001, "attributes": [ "notSelectable" ] }, { "id": 1002, "attributes": [ "notSelectable" ] } ], "global": {} }, "attributes": [] } }
GET

Get selectable issue field options

Returns a paginated list of options for a select list issue field that can be viewed and selected by the user.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Permissions required: Permission to access Jira.

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredNONE

ClassicRECOMMENDED:read:jira-work
Granular:read:field.option:jira

Request

Path parameters

fieldKey

string

Required

Query parameters

startAt

integer

maxResults

integer

projectId

integer

Responses

Returned if the request is successful.

application/json

PageBeanIssueFieldOption

A page of items.

GET/rest/api/2/field/{fieldKey}/option/suggestions/edit
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/2/field/{fieldKey}/option/suggestions/edit`, { 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": false, "maxResults": 1, "nextPage": "https://your-domain.atlassian.net/rest/api/2/field/fieldKey/option/suggestions?startAt=1&maxResults=1", "self": "https://your-domain.atlassian.net/rest/api/2/field/fieldKey/option/suggestions?startAt=0&maxResults=1", "startAt": 0, "total": 10, "values": [ { "id": 1, "value": "Team 1", "properties": { "leader": { "name": "Leader Name", "email": "lname@example.com" }, "members": 42, "description": "The team's description", "founded": "2016-06-06" } } ] }
GET

Get visible issue field options

Returns a paginated list of options for a select list issue field that can be viewed by the user.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Permissions required: Permission to access Jira.

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredNONE

ClassicRECOMMENDED:read:jira-work
Granular:read:field.option:jira

Request

Path parameters

fieldKey

string

Required

Query parameters

startAt

integer

maxResults

integer

projectId

integer

Responses

Returned if the request is successful.

application/json

PageBeanIssueFieldOption

A page of items.

GET/rest/api/2/field/{fieldKey}/option/suggestions/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/2/field/{fieldKey}/option/suggestions/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 { "isLast": false, "maxResults": 1, "nextPage": "https://your-domain.atlassian.net/rest/api/2/field/fieldKey/option/suggestions?startAt=1&maxResults=1", "self": "https://your-domain.atlassian.net/rest/api/2/field/fieldKey/option/suggestions?startAt=0&maxResults=1", "startAt": 0, "total": 10, "values": [ { "id": 1, "value": "Team 1", "properties": { "leader": { "name": "Leader Name", "email": "lname@example.com" }, "members": 42, "description": "The team's description", "founded": "2016-06-06" } } ] }
GET

Get issue field option

Returns an option from a select list issue field.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredNONE

ClassicRECOMMENDED:manage:jira-configuration
Granular:read:field.option:jira

Request

Path parameters

fieldKey

string

Required
optionId

integer

Required

Responses

Returned if the requested option is returned.

application/json

IssueFieldOption

Details of the options for a select list issue field.

GET/rest/api/2/field/{fieldKey}/option/{optionId}
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/2/field/{fieldKey}/option/{optionId}`, { 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 { "id": 1, "value": "Team 1", "properties": { "leader": { "name": "Leader Name", "email": "lname@example.com" }, "members": 42, "description": "The team's description", "founded": "2016-06-06" }, "config": { "scope": { "projects": [], "projects2": [ { "id": 1001, "attributes": [ "notSelectable" ] }, { "id": 1002, "attributes": [ "notSelectable" ] } ], "global": {} }, "attributes": [] } }
PUT

Update issue field option

Updates or creates an option for a select list issue field. This operation requires that the option ID is provided when creating an option, therefore, the option ID needs to be specified as a path and body parameter. The option ID provided in the path and body must be identical.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredNONE

ClassicRECOMMENDED:manage:jira-configuration
Granular:write:field.option:jira

Request

Path parameters

fieldKey

string

Required
optionId

integer

Required

Request bodyapplication/json

config

IssueFieldOptionConfiguration

id

integer

Required
properties

object

value

string

Required

Responses

Returned if the option is updated or created.

application/json

IssueFieldOption

Details of the options for a select list issue field.

PUT/rest/api/2/field/{fieldKey}/option/{optionId}
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 50 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "config": { "attributes": [], "scope": { "global": {}, "projects": [], "projects2": [ { "attributes": [ "notSelectable" ], "id": 1001 }, { "attributes": [ "notSelectable" ], "id": 1002 } ] } }, "id": 1, "properties": { "description": "The team's description", "founded": "2016-06-06", "leader": { "email": "lname@example.com", "name": "Leader Name" }, "members": 42 }, "value": "Team 1" }`; const response = await api.asUser().requestJira(route`/rest/api/2/field/{fieldKey}/option/{optionId}`, { method: 'PUT', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); 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 { "id": 1, "value": "Team 1", "properties": { "leader": { "name": "Leader Name", "email": "lname@example.com" }, "members": 42, "description": "The team's description", "founded": "2016-06-06" }, "config": { "scope": { "projects": [], "projects2": [ { "id": 1001, "attributes": [ "notSelectable" ] }, { "id": 1002, "attributes": [ "notSelectable" ] } ], "global": {} }, "attributes": [] } }
DEL

Delete issue field option

Deletes an option from a select list issue field.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredNONE

ClassicRECOMMENDED:manage:jira-configuration
Granular:delete:field.option:jira

Request

Path parameters

fieldKey

string

Required
optionId

integer

Required

Responses

Returned if the field option is deleted.

application/json

any

DEL/rest/api/2/field/{fieldKey}/option/{optionId}
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/2/field/{fieldKey}/option/{optionId}`, { method: 'DELETE', headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
DEL

Replace issue field option

Deselects an issue-field select-list option from all issues where it is selected. A different option can be selected to replace the deselected option. The update can also be limited to a smaller set of issues by using a JQL query.

Connect and Forge app users with Administer Jira global permission can override the screen security configuration using overrideScreenSecurity and overrideEditableFlag.

This is an asynchronous operation. The response object contains a link to the long-running task.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredNONE

ClassicRECOMMENDED:manage:jira-configuration
Granular:write:field.option:jira, delete:field.option:jira

Request

Path parameters

fieldKey

string

Required
optionId

integer

Required

Query parameters

replaceWith

integer

jql

string

overrideScreenSecurity

boolean

overrideEditableFlag

boolean

Responses

Returned if the long-running task to deselect the option is started.

application/json

TaskProgressBeanRemoveOptionFromIssuesResult

Details about a task.

DEL/rest/api/2/field/{fieldKey}/option/{optionId}/issue
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/2/field/{fieldKey}/option/{optionId}/issue`, { 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 15 16 17 18 19 20 21 22 23 24 25 26 { "self": "https://your-domain.atlassian.net/rest/api/2/task/1", "id": "1", "description": "Remove option 1 from issues matched by '*', and replace with option 3", "status": "COMPLETE", "result": { "errors": { "errorMessages": [ "Option 2 cannot be set on issue MKY-5 as it is not in the correct scope" ], "errors": {}, "httpStatusCode": { "empty": false, "present": true } }, "modifiedIssues": [ 10001, 10010 ], "unmodifiedIssues": [ 10005 ] }, "elapsedRuntime": 42 }

Rate this page: