# 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](api-entity-CustomField.html).

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

```CURL
curl -X GET \
'https://example.youtrack.cloud/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

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

## 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](api-entity-ProjectCustomField.html).

The following sample shows how to get all custom fields with their settings in a particular project.

### Sample Request

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

### Sample Response Body

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

The `ProjectCustomField` entity does not have a direct `multi` property. To check whether a project field stores multiple values, request the `field.fieldType.isMultiValue` attribute of the linked `CustomField`. The `field.fieldType.id` value also includes the cardinality suffix, for example `user[*]` for a multi-value user field.

## 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).

The exact type of the `value` attribute depends on the `$type` of the `IssueCustomField`. For example, user fields return a `User` entity, enum and state fields return bundle elements, version fields can return a collection of bundle elements, and simple fields return primitive values.

For the complete list of the `IssueCustomField` attributes, see [IssueCustomField](api-entity-IssueCustomField.html).

To retrieve custom fields for a specific issue, send a `GET` request to `/api/issues/{issueID}/customFields`.

The following sample shows how to get all custom fields with their values in a particular issue.

### Sample Request

```CURL
curl -X GET \
'https://example.youtrack.cloud/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

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

In this response, the `Priority` field returns an `EnumBundleElement`, while the `Assignee` field returns a `User` entity. Other custom fields can return different value types depending on the `IssueCustomField` `$type`.

For more examples of how to request and interpret specific custom field values, see [Get Value for an Issue Custom Field](api-howto-get-value-for-specific-cf.html).

### Examples for Other Field Types

The following examples show common shapes of the `value` attribute for other `IssueCustomField` types. Request only the nested value attributes you need in the `fields` parameter.

Multi-value fields return an array of values. For example, a multi-value version field can return:

```JSON
{
    "name": "Fix versions",
    "value": [
        {
            "name": "2026.1",
            "id": "133-19",
            "$type": "VersionBundleElement"
        },
        {
            "name": "2026.2",
            "id": "133-24",
            "$type": "VersionBundleElement"
        }
    ],
    "id": "92-4",
    "$type": "MultiVersionIssueCustomField"
}
```

State, build, owned, enum, version, group, and user fields return bundle elements or entities. The exact entity type depends on the field type:

```JSON
{
    "name": "State",
    "value": {
        "name": "In Progress",
        "isResolved": false,
        "id": "78-2",
        "$type": "StateBundleElement"
    },
    "id": "92-3",
    "$type": "StateIssueCustomField"
}
```

```JSON
{
    "name": "Fixed in build",
    "value": {
        "name": "2026.1.45678",
        "id": "95-12",
        "$type": "BuildBundleElement"
    },
    "id": "92-8",
    "$type": "SingleBuildIssueCustomField"
}
```

Simple fields return primitive values. Date and date-time fields return timestamps in milliseconds.

```JSON
{
    "name": "Customer email",
    "value": "jane.doe@example.com",
    "id": "92-9",
    "$type": "SimpleIssueCustomField"
}
```

```JSON
{
    "name": "Due Date",
    "value": 1782864000000,
    "id": "92-10",
    "$type": "DateIssueCustomField"
}
```

Period fields return a `PeriodValue` object.

```JSON
{
    "name": "Estimation",
    "value": {
        "minutes": 150,
        "presentation": "2h 30m",
        "id": "150-1",
        "$type": "PeriodValue"
    },
    "id": "92-11",
    "$type": "PeriodIssueCustomField"
}
```

Text fields return a text value object with the source text and rendered Markdown.

```JSON
{
    "name": "Release notes",
    "value": {
        "text": "Fixed in the latest build.",
        "markdownText": "<p>Fixed in the latest build.</p>",
        "id": "150-2",
        "$type": "TextFieldValue"
    },
    "id": "92-12",
    "$type": "TextIssueCustomField"
}
```

## $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.

The `ProjectCustomField` `$type` does not distinguish single-value fields from multi-value fields for all field types. For example, both `version[1]` and `version[*]` use `VersionProjectCustomField`. Use `field.fieldType.isMultiValue` or the `[*]` suffix in `field.fieldType.id` when you need to identify multi-value project fields.

| 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` |
| `integer` | `SimpleIssueCustomField` | `SimpleProjectCustomField` |
| `float` | `SimpleIssueCustomField` | `SimpleProjectCustomField` |
| `date` | `DateIssueCustomField` | `SimpleProjectCustomField` |
| `date and time` | `SimpleIssueCustomField` | `SimpleProjectCustomField` |
| `period` | `PeriodIssueCustomField` | `PeriodProjectCustomField` |
| `string` | `SimpleIssueCustomField` | `SimpleProjectCustomField` |
| `text` | `TextIssueCustomField` | `TextProjectCustomField` |

When you set or update a custom field, the format of the `value` attribute depends on the field type:

* Single-value enum, build, state, version, owned, user, and group fields use a single value object, for example `{"name": "Major"}` for an enum value or `{"login": "jane.doe"}` for a user.

* Multi-value enum, build, version, owned, user, and group fields use an array of value objects.

* Integer, float, and string fields use primitive values.

* Date and date-time fields use timestamps in milliseconds.

* Period fields use a `PeriodValue` object, for example `{"minutes": 150}` or `{"presentation": "2h 30m"}`.

* Text fields use a `TextFieldValue` object, for example `{"text": "Some text"}`.