Atlassian: Create custom field
Atlassian issueFields.createCustomField: arguments, response, policy and SDK examples.
← Issue fields operations · Get started
Operation atlassian.createcustomfield
Provider route: POST /{cloudId}/rest/api/3/field. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/atlassian with npm, or alter-sdk-atlassian with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { AtlassianIntegration } from "@alter-ai/atlassian";
async function execute(input: Parameters<AtlassianIntegration["issueFields"]["createCustomField"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new AtlassianIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.issueFields.createCustomField(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_atlassian import AtlassianIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = AtlassianIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.issue_fields.create_custom_field(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.cloudId | string | Required within parent | Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
body | Model | Required within parent | Expand Create custom field — request body — body |
Referenced models: Create custom field — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Create custom field — response body |
Referenced models: Create custom field — response body
Schemas
Section titled “Schemas”4 more schemas are linked from the tables above, on the schema pages.
Create custom field — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
description | string | Optional | The description of the custom field, which is displayed in Jira. |
name | string | Required within parent | The name of the custom field, which is displayed in Jira. This is not the unique identifier. |
searcherKey | 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](https://developer.atlassian.com/platform/forge/manifest-reference/modules/#jira-custom-field-type--beta-) have a searcher set automatically, so are always searchable. One of: 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 |
type | string | Required within parent | 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`. |
Create custom field — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Details about a field. |
clauseNames | JSON | Optional | |
clauseNames (anyOf 1) | array | Alternative | 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). Unique items: true |
clauseNames (anyOf 1)[] | string | Each item | |
clauseNames (anyOf 2) | null | Alternative | |
custom | JSON | Optional | |
custom (anyOf 1) | boolean | Alternative | Whether the field is a custom field. |
custom (anyOf 2) | null | Alternative | |
id | JSON | Optional | |
id (anyOf 1) | string | Alternative | The ID of the field. |
id (anyOf 2) | null | Alternative | |
key | JSON | Optional | |
key (anyOf 1) | string | Alternative | The key of the field. |
key (anyOf 2) | null | Alternative | |
name | JSON | Optional | |
name (anyOf 1) | string | Alternative | The name of the field. |
name (anyOf 2) | null | Alternative | |
navigable | JSON | Optional | |
navigable (anyOf 1) | boolean | Alternative | Whether the field can be used as a column on the issue navigator. |
navigable (anyOf 2) | null | Alternative | |
orderable | JSON | Optional | |
orderable (anyOf 1) | boolean | Alternative | Whether the content of the field can be used to order lists. |
orderable (anyOf 2) | null | Alternative | |
schema | JSON | Optional | |
schema (anyOf 1) | Model | Alternative | Expand Create custom field — response body — schema The schema of a field The data schema for the field. |
schema (anyOf 2) | null | Alternative | |
scope | JSON | Optional | |
scope (anyOf 1) | Model | Alternative | Expand Get status — response body — scope project, type The scope of the field. |
scope (anyOf 2) | null | Alternative | |
searchable | JSON | Optional | |
searchable (anyOf 1) | boolean | Alternative | Whether the content of the field can be searched. |
searchable (anyOf 2) | null | Alternative |
Referenced models: Create custom field — response body — schema The schema of a field, Get status — response body — scope project, type
Create custom field — response body — schema The schema of a field
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The schema of a field. |
configuration | JSON | Optional | |
configuration (anyOf 1) | object | Alternative | If the field is a custom field, the configuration of the field. Read only: true Additional keys: see wildcard field |
configuration (anyOf 1).* | JSON | Additional keys | Read only: true |
configuration (anyOf 2) | null | Alternative | |
custom | JSON | Optional | |
custom (anyOf 1) | string | Alternative | If the field is a custom field, the URI of the field. Read only: true |
custom (anyOf 2) | null | Alternative | |
customId | JSON | Optional | |
customId (anyOf 1) | JSON | Alternative | |
customId (anyOf 1) (anyOf 1) | integer | Alternative | If the field is a custom field, the custom ID of the field. Format: int64 Read only: true |
customId (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
customId (anyOf 2) | null | Alternative | |
items | JSON | Optional | |
items (anyOf 1) | string | Alternative | When the data type is an array, the name of the field items within the array. Read only: true |
items (anyOf 2) | null | Alternative | |
system | JSON | Optional | |
system (anyOf 1) | string | Alternative | If the field is a system field, the name of the field. Read only: true |
system (anyOf 2) | null | Alternative | |
type | JSON | Optional | |
type (anyOf 1) | string | Alternative | The data type of the field. Read only: true |
type (anyOf 2) | null | Alternative |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: atlassian.createcustomfield. Catalog operation: createcustomfield. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["manage:jira-configuration"]