Skip to content
forgit api docs

Create issue field for an organization

POST
/orgs/{org}/issue-fields

Creates a new issue field for an organization.

You can find out more about issue fields in Managing issue fields in an organization.

To use this endpoint, the authenticated user must be an administrator for the organization. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
name
required

Name of the issue field.

string
description

Description of the issue field.

string
nullable
data_type
required

The data type of the issue field.

string
Allowed values: text date single_select multi_select number
visibility

The visibility of the issue field. Can be organization_members_only (visible only within the organization) or all (visible to all users who can see issues). Only used when the visibility settings feature is enabled. Defaults to organization_members_only.

string
Allowed values: organization_members_only all
options

Options for select fields. Required when data_type is ‘single_select’ or ‘multi_select’.

Array<object>
nullable
object
name
required

Name of the option.

string
description

Description of the option.

string
nullable
color
required

Color for the option.

string
Allowed values: gray blue green yellow orange red pink purple
priority
required

Priority of the option for ordering.

integer
Examples
Example default 
{
  "name": "Priority",
  "description": "Level of importance for the issue",
  "data_type": "single_select",
  "options": [
    {
      "name": "High",
      "description": "High priority",
      "color": "red"
    },
    {
      "name": "Medium",
      "description": "Medium priority",
      "color": "yellow"
    },
    {
      "name": "Low",
      "description": "Low priority",
      "color": "green"
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response

Media type application/json
Issue Field

A custom attribute defined at the organization level for attaching structured data to issues.

object
id
required

The unique identifier of the issue field.

integer
node_id
required

The node identifier of the issue field.

string
name
required

The name of the issue field.

string
description

The description of the issue field.

string
nullable
data_type
required

The data type of the issue field.

string
Allowed values: text date single_select multi_select number
visibility

The visibility of the issue field. Can be organization_members_only (visible only within the organization) or all (visible to all users who can see issues).

string
Allowed values: organization_members_only all
options

Available options for single select and multi select fields.

Array<object>
nullable
object
id
required

The unique identifier of the option.

integer
name
required

The name of the option.

string
description

The description of the option.

string
nullable
color

The color of the option.

string
nullable
Allowed values: gray blue green yellow orange red pink purple
priority

The priority of the option for ordering.

integer
nullable
created_at

The time the option was created.

string format: date-time
updated_at

The time the option was last updated.

string format: date-time
created_at

The time the issue field was created.

string format: date-time
updated_at

The time the issue field was last updated.

string format: date-time
Examples
Example default 
{
  "id": 512,
  "node_id": "IF_kwDNAd3NAZr",
  "name": "Priority",
  "description": "Level of importance for the issue",
  "data_type": "single_select",
  "options": [
    {
      "id": 1,
      "name": "High",
      "description": "High priority",
      "color": "red",
      "priority": 1,
      "created_at": "2025-01-15T10:30:15Z",
      "updated_at": "2025-01-15T10:30:15Z"
    },
    {
      "id": 2,
      "name": "Medium",
      "description": "Medium priority",
      "color": "yellow",
      "priority": 2,
      "created_at": "2025-01-15T10:30:15Z",
      "updated_at": "2025-01-15T10:30:15Z"
    },
    {
      "id": 3,
      "name": "Low",
      "description": "Low priority",
      "color": "green",
      "priority": 3,
      "created_at": "2025-01-15T10:30:15Z",
      "updated_at": "2025-01-15T10:30:15Z"
    }
  ],
  "created_at": "2025-01-15T10:30:15Z",
  "updated_at": "2025-01-15T10:30:15Z"
}

404

Section titled “ 404 ”

Resource not found

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error Simple

Validation Error Simple

object
message
required
string
documentation_url
required
string
errors
Array<string>
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    "example"
  ]
}