--- title: "Create custom field" method: POST path: "/rest/api/3/field" tags: ["Issue fields"] --- # Create custom field `POST /rest/api/3/field` Creates a custom field. **[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg). ## Request body - CustomFieldDefinitionJsonBean - `description` string — 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` 'com.atlassian.jira.plugin.system.customfieldtypes:cascadingselectsearcher' | 'com.atlassian.jira.plugin.system.customfieldtypes:daterange' | 'com.atlassian.jira.plugin.system.customfieldtypes:datetimerange' | 'com.atlassian.jira.plugin.system.customfieldtypes:exactnumber' | 'com.atlassian.jira.plugin.system.customfieldtypes:exacttextsearcher' | 'com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher' | 'com.atlassian.jira.plugin.system.customfieldtypes:labelsearcher' | 'com.atlassian.jira.plugin.system.customfieldtypes:multiselectsearcher' | 'com.atlassian.jira.plugin.system.customfieldtypes:numberrange' | 'com.atlassian.jira.plugin.system.customfieldtypes:projectsearcher' | 'com.atlassian.jira.plugin.system.customfieldtypes:textsearcher' | 'com.atlassian.jira.plugin.system.customfieldtypes:userpickergroupsearcher' | 'com.atlassian.jira.plugin.system.customfieldtypes:versionsearcher' — 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](https://developer.atlassian.com/platform/forge/manifest-reference/modules/#jira-custom-field-type--beta-) have a searcher set automatically, so are always searchable. - `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](https://developer.atlassian.com/platform/forge/manifest-reference/modules/#jira-custom-field-type--beta-), 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`. ## Response `201` Returned if the custom field is created. - FieldDetails — Details about a field. - `clauseNames` string[] — The names that can be used to reference the field in an advanced search. For more information, see [Advanced searching - fields reference](https://confluence.atlassian.com/x/gwORLQ). - `custom` boolean — Whether the field is a custom field. - `id` string — The ID of the field. - `key` string — The key of the field. - `name` string — The name of the field. - `navigable` boolean — Whether the field can be used as a column on the issue navigator. - `orderable` boolean — Whether the content of the field can be used to order lists. - `schema` JsonTypeBean — The schema of a field. - `configuration` object — If the field is a custom field, the configuration of the field. - `custom` string — If the field is a custom field, the URI of the field. - `customId` integer — If the field is a custom field, the custom ID of the field. - `items` string — When the data type is an array, the name of the field items within the array. - `system` string — If the field is a system field, the name of the field. - `type` string, required — The data type of the field. - `scope` Scope — The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO). - `project` ProjectDetails — Details about a project. - `avatarUrls` AvatarUrlsBean - `16x16` string, uri — The URL of the item's 16x16 pixel avatar. - `24x24` string, uri — The URL of the item's 24x24 pixel avatar. - `32x32` string, uri — The URL of the item's 32x32 pixel avatar. - `48x48` string, uri — The URL of the item's 48x48 pixel avatar. - `id` string — The ID of the project. - `key` string — The key of the project. - `name` string — The name of the project. - `projectCategory` UpdatedProjectCategory — A project category. - `description` string — The name of the project category. - `id` string — The ID of the project category. - `name` string — The description of the project category. - `self` string — The URL of the project category. - `projectTypeKey` 'software' | 'service_desk' | 'business' — The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project. - `self` string — The URL of the project details. - `simplified` boolean — Whether or not the project is simplified. - `type` 'PROJECT' | 'TEMPLATE' — The type of scope. - `searchable` boolean — Whether the content of the field can be searched. ## Other responses - `400` — Returned if: * the user does not have permission to create custom fields. * any of the request object properties have invalid or missing values. --- [API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api-2/versions/ec7f275dfee5/schema)