Custom Fields in REST API

This page describes the hierarchy of custom fields in YouTrack and how the CustomField, ProjectCustomField, and IssueCustomField entities differ from each other.

CustomField

CustomField is an entity that defines a common custom field which contains basic attributes like "name", "fieldType" and other described on the JSON Schema page. Notice that "instances" property contains setting of this field in different projects.

The following sample shows how to get custom fields. By default, YouTrack returns only $type and id attributes of the requested entities. To get more information about custom fields, we explicitly provide a list of returned entity attributes in the fields parameter of the request. Notice that $type attribute will be in response regardless of whether you specify it explicitly or not.

Sample request

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/admin/customFieldSettings/customFields?fields=id,name,aliases,instances(id,project(id,name))' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
        

Sample response body

[
    ...
    {
        "id":"58-1",
        "name":"Priority",
        "$type":"CustomField",
        "aliases":null,
        "instances":[
            {
                "id":"92-1",
                "$type":"EnumProjectCustomField",
                "project":{
                    "id":"0-0",
                    "name":"Sample Project"
                }
            },
            ...
        ]
    },
    ...
    {
        "id":"58-4",
        "name":"Assignee",
        "$type":"CustomField",
        "aliases":"for, assigned to",
        "instances":[
            {
                "id":"94-0",
                "$type":"UserProjectCustomField",
                "project":{
                    "id":"0-0",
                    "name":"Sample Project"
                }
            },
            ...
        ]
    },
    ...
]
        

ProjectCustomField

ProjectCustomField entity contains settings of a CustomField ("field" attribute) in a particular project ("project"), such as the set of possible values ("bundle"), whether the field can be empty or not ("canBeEmpty") and so on. For the complete list of attributes, see the JSON Schema page.

Sample request

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/admin/projects/0-0/customFields?fields=id,canBeEmpty,emptyFieldText,project(id,name),field(id,name)' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
        

Sample response body

[
    ...
    {
        "id":"92-1",
        "$type":"EnumProjectCustomField",
        "canBeEmpty":false,
        "emptyFieldText":"No Priority",
        "field":{
            "id":"58-1",
            "name":"Priority",
            "$type":"CustomField"
        },
        "project":{
            "id":"0-0",
            "name":"Sample Project"
        }
    },
    ...
    {
        "id":"94-0",
        "$type":"UserProjectCustomField",
        "canBeEmpty":true,
        "emptyFieldText":"Unassigned",
        "field":{
            "id":"58-4",
            "name":"Assignee",
            "$type":"CustomField"
        },
        "project":{
            "id":"0-0",
            "name":"Sample Project"
        }
    },
    ...
]
    

IssueCustomField

The IssueCustomField entity contains a value ("value" attribute) of a ProjectCustomField ("projectCustomField") for particular issue. The value can be a simple one (string, integer,..), a link to an existing entity (link to particular user for Assignee field), or a collection of values (Affected versions field).

Sample request:

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/issues/2-7/customFields?fields=id,value(id,name,login,fullName),projectCustomField(id,field(id,name))' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
        

Sample response body:

[
    {
        "id":"92-1",
        "$type":"SingleEnumIssueCustomField",
        "projectCustomField":{
            "id":"92-1",
            "$type":"EnumProjectCustomField",
            "field":{
                "id":"58-1",
                "name":"Priority",
                "$type":"CustomField"
            }
        },
        "value":{
            "id":"67-2",
            "name":"Major",
            "$type":"EnumBundleElement"
        }
    },
    ...
    {
        "id":"94-0",
        "$type":"SingleUserIssueCustomField",
        "projectCustomField":{
            "id":"94-0",
            "$type":"UserProjectCustomField",
            "field":{
                "id":"58-4",
                "name":"Assignee",
                "$type":"CustomField"
            }
        },
        "value":{
            "id":"1-3",
            "login":"jane.doe",
            "fullName":"Jane Doe",
            "name":"Jane Doe",
            "$type":"User"
        }
    },
    ...
]
    

$type Mapping for Custom Fields

The following table shows the mapping between supported issue custom fields and their corresponding $type values. You must provide the $type value in the POST request when you need to set or update a custom field in an issue.

Custom Field Type	IssueCustomField `$type`	ProjectCustomField `$type`
`enum[1]`	`SingleEnumIssueCustomField`	`EnumProjectCustomField`
`enum[*]`	`MultiEnumIssueCustomField`	`EnumProjectCustomField`
`build[1]`	`SingleBuildIssueCustomField`	`BuildProjectCustomField`
`build[*]`	`MultiBuildIssueCustomField`	`BuildProjectCustomField`
`state[1]`	`StateIssueCustomField`	`StateProjectCustomField`
`version[1]`	`SingleVersionIssueCustomField`	`VersionProjectCustomField`
`version[*]`	`MultiVersionIssueCustomField`	`VersionProjectCustomField`
`ownedField[1]`	`SingleOwnedIssueCustomField`	`OwnedProjectCustomField`
`ownedField[*]`	`MultiOwnedIssueCustomField`	`OwnedProjectCustomField`
`user[1]`	`SingleUserIssueCustomField`	`UserProjectCustomField`
`user[*]`	`MultiUserIssueCustomField`	`UserProjectCustomField`
`group[1]`	`SingleGroupIssueCustomField`	`GroupProjectCustomField`
`group[*]`	`MultiGroupIssueCustomField`	`GroupProjectCustomField`
`int`	`SimpleIssueCustomField`	`SimpleProjectCustomField`
`float`	`SimpleIssueCustomField`	`SimpleProjectCustomField`
`date`	`DateIssueCustomField`	`SimpleProjectCustomField`
`date and time`	`SimpleIssueCustomField`	`SimpleProjectCustomField`
`period`	`PeriodIssueCustomField`	`PeriodProjectCustomField`
`string`	`SimpleIssueCustomField`	`SimpleProjectCustomField`
`text`	`TextIssueCustomField`	`TextProjectCustomField`

Last modified: 1 July 2020