Create custom field

POST

/rest/api/3/field

Issue fields

Creates a custom field.

Permissions required: Administer Jira global permission.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'http://jira.local:8080/jira/rest//rest/api/3/field' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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"
}'

Response Example

201 - Success

{
  "id": "customfield_10101",
  "key": "customfield_10101",
  "name": "New custom field",
  "untranslatedName": "New custom field",
  "custom": true,
  "orderable": true,
  "navigable": true,
  "searchable": true,
  "clauseNames": [
    "cf[10101]",
    "New custom field"
  ],
  "schema": {
    "type": "project",
    "custom": "com.atlassian.jira.plugin.system.customfieldtypes:project",
    "customId": 10101
  }
}

Request

Body Params application/json

description

string

optional

The description of the custom field, which is displayed in Jira.

name

string

required

The name of the custom field, which is displayed in Jira. This is not the unique identifier.

searcherKey

enum<string>

optional

The searcher defines the way the field is searched in Jira. For example, com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher.
The search UI (basic search and JQL search) will display different operations and values for the field, based on the field searcher. You must specify a searcher that is valid for the field type, as listed below (abbreviated values shown):

cascadingselect: cascadingselectsearcher

datepicker: daterange

datetime: datetimerange

float: exactnumber or numberrange

grouppicker: grouppickersearcher

importid: exactnumber or numberrange

labels: labelsearcher

multicheckboxes: multiselectsearcher

multigrouppicker: multiselectsearcher

multiselect: multiselectsearcher

multiuserpicker: userpickergroupsearcher

multiversion: versionsearcher

project: projectsearcher

radiobuttons: multiselectsearcher

readonlyfield: textsearcher

select: multiselectsearcher

textarea: textsearcher

textfield: textsearcher

url: exacttextsearcher

userpicker: userpickergroupsearcher

version: versionsearcher

If no searcher is provided, the field isn't searchable. However, Forge custom fields have a searcher set automatically, so are always searchable.

Allowed values:

com.atlassian.jira.plugin.system.customfieldtypes:cascadingselectsearchercom.atlassian.jira.plugin.system.customfieldtypes:daterangecom.atlassian.jira.plugin.system.customfieldtypes:datetimerangecom.atlassian.jira.plugin.system.customfieldtypes:exactnumbercom.atlassian.jira.plugin.system.customfieldtypes:exacttextsearchercom.atlassian.jira.plugin.system.customfieldtypes:grouppickersearchercom.atlassian.jira.plugin.system.customfieldtypes:labelsearchercom.atlassian.jira.plugin.system.customfieldtypes:multiselectsearchercom.atlassian.jira.plugin.system.customfieldtypes:numberrangecom.atlassian.jira.plugin.system.customfieldtypes:projectsearchercom.atlassian.jira.plugin.system.customfieldtypes:textsearchercom.atlassian.jira.plugin.system.customfieldtypes:userpickergroupsearchercom.atlassian.jira.plugin.system.customfieldtypes:versionsearcher

type

string

required

The type of the custom field. These built-in custom field types are available:

cascadingselect: Enables values to be selected from two levels of select lists (value: com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect)

datepicker: Stores a date using a picker control (value: com.atlassian.jira.plugin.system.customfieldtypes:datepicker)

datetime: Stores a date with a time component (value: com.atlassian.jira.plugin.system.customfieldtypes:datetime)

float: Stores and validates a numeric (floating point) input (value: com.atlassian.jira.plugin.system.customfieldtypes:float)

grouppicker: Stores a user group using a picker control (value: com.atlassian.jira.plugin.system.customfieldtypes:grouppicker)

importid: A read-only field that stores the ID the issue had in the system it was imported from (value: com.atlassian.jira.plugin.system.customfieldtypes:importid)

labels: Stores labels (value: com.atlassian.jira.plugin.system.customfieldtypes:labels)

multicheckboxes: Stores multiple values using checkboxes (value: ``)

multigrouppicker: Stores multiple user groups using a picker control (value: ``)

multiselect: Stores multiple values using a select list (value: com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes)

multiuserpicker: Stores multiple users using a picker control (value: com.atlassian.jira.plugin.system.customfieldtypes:multigrouppicker)

multiversion: Stores multiple versions from the versions available in a project using a picker control (value: com.atlassian.jira.plugin.system.customfieldtypes:multiversion)

project: Stores a project from a list of projects that the user is permitted to view (value: com.atlassian.jira.plugin.system.customfieldtypes:project)

radiobuttons: Stores a value using radio buttons (value: com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons)

readonlyfield: Stores a read-only text value, which can only be populated via the API (value: com.atlassian.jira.plugin.system.customfieldtypes:readonlyfield)

select: Stores a value from a configurable list of options (value: com.atlassian.jira.plugin.system.customfieldtypes:select)

textarea: Stores a long text string using a multiline text area (value: com.atlassian.jira.plugin.system.customfieldtypes:textarea)

textfield: Stores a text string using a single-line text box (value: com.atlassian.jira.plugin.system.customfieldtypes:textfield)

url: Stores a URL (value: com.atlassian.jira.plugin.system.customfieldtypes:url)

userpicker: Stores a user using a picker control (value: com.atlassian.jira.plugin.system.customfieldtypes:userpicker)

version: Stores a version using a picker control (value: com.atlassian.jira.plugin.system.customfieldtypes:version)

To create a field based on a Forge custom field type, use the ID of the Forge custom field type as the value. For example,

ari:cloud:ecosystem::extension/e62f20a2-4b61-4dbe-bfb9-9a88b5e3ac84/548c5df1-24aa-4f7c-bbbb-3038d947cb05/static/my-cf-type-key

Examples

Responses

🟢201Returned if the custom field is created.

application/json

Body

Details about a field.

clauseNames

array[string]

optional

The names that can be used to reference the field in an advanced search. For more information, see Advanced searching - fields reference.

custom

boolean

optional

Whether the field is a custom field.

string

optional

The ID of the field.

key

string

optional

The key of the field.

name

string

optional

The name of the field.

navigable

boolean

optional

Whether the field can be used as a column on the issue navigator.

orderable

boolean

optional

Whether the content of the field can be used to order lists.

schema

object

optional

The data schema for the field.

configuration

object

read-onlyoptional

If the field is a custom field, the configuration of the field.

custom

string

read-onlyoptional

If the field is a custom field, the URI of the field.

customId

integer <int64>

read-onlyoptional

If the field is a custom field, the custom ID of the field.

items

string

read-onlyoptional

When the data type is an array, the name of the field items within the array.

system

string

read-onlyoptional

If the field is a system field, the name of the field.

type

string

read-onlyrequired

The data type of the field.

scope

object

optional

The scope of the field.

project

object

read-onlyoptional

The project the item has scope in.

type

enum<string>

read-onlyoptional

The type of scope.

Allowed values:

PROJECTTEMPLATE

Additional properties

integer | number | string | boolean

optional

searchable

boolean

optional

Whether the content of the field can be searched.

🟠400Returned if: * the user does not have permission to create custom fields. * any of the request object properties have invalid or missing values.

Modified at 2023-07-13 03:27:27

Get fields

Get fields paginated