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
and fieldType
. The instances
property contains the settings for this field in different projects.
For the complete list of the CustomField
attributes, see CustomField.
The following sample shows how to get all custom fields in YouTrack. By default, YouTrack returns only the $type
attribute 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. The $type
attribute will appear in the response regardless of whether you specify it explicitly or not.
Sample Request
Sample Response Body
ProjectCustomField
ProjectCustomField
is an entity that contains settings of a CustomField
(the 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 the ProjectCustomField
attributes, see ProjectCustomField.
The following sample shows how to get all custom fields with their settings in a particular project.
Sample Request
Sample Response Body
IssueCustomField
The IssueCustomField
entity contains the value (the value
attribute) of a ProjectCustomField
(projectCustomField
) in a particular issue. The value can be a simple one (for example, string
or integer
), a link to an existing entity (a link to a specific user for the Assignee
field), or a collection of values (the Affected versions
field).
For the complete list of the IssueCustomField
attributes, see IssueCustomField.
The following sample shows how to get all custom fields with their values in a particular issue.
Sample Request
Sample Response Body
$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 | ProjectCustomField |
---|---|---|
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 |
integer | SimpleIssueCustomField | SimpleProjectCustomField |
float | SimpleIssueCustomField | SimpleProjectCustomField |
date | DateIssueCustomField | SimpleProjectCustomField |
date and time | SimpleIssueCustomField | SimpleProjectCustomField |
period | PeriodIssueCustomField | PeriodProjectCustomField |
string | SimpleIssueCustomField | SimpleProjectCustomField |
text | TextIssueCustomField | TextProjectCustomField |