---
schema: rendered-html/v1
title: "Custom Fields in REST API | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/api-concept-custom-fields.html
generated_at: 2026-06-11T14:44:19.739682+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Get Started with REST API
- Log in to YouTrack
- REST API URL and Endpoints
- OpenAPI Specification (OAS)
- Fields Syntax
- Query Syntax
- Request Headers
- [Custom Fields in REST API](api-concept-custom-fields.html)
- [Pagination](jetbrains__com__help__youtrack__devportal__api-concept-pagination.md)
- Users, Groups, and Access Management
- Hub REST API Endpoints Deprecated in YouTrack 2026.1
- Postman Collection for the YouTrack REST API
- REST API Reference
- REST API Use Cases
- REST API Troubleshooting
- Color Indices List
- Hub REST API

1. YouTrack REST API
2. Get Started with REST API
3. [Custom Fields in REST API](#0)

# Custom Fields in REST API﻿

Last modified: 07 May 2026

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﻿

```
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﻿

```
[
    ...
    {
        "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.

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

### Sample Request﻿

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

```
[
    ...
    {
        "field": {
            "name": "Priority",
            "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",
            "$type":"CustomField"
        },
        "project": {
            "name": "Sample Project",
            "id": "0-0",
            "$type": "Project"
        },
        "emptyFieldText":"Unassigned",
        "canBeEmpty":true,
        "id":"94-0",
        "$type":"UserProjectCustomField"
},
    ...
]
```

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

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 -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﻿

```
[
    {
        "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.

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

- [Custom Fields in REST API](/help/youtrack/devportal/api-concept-custom-fields.html)
- [CustomField](/help/youtrack/devportal/api-concept-custom-fields.html#custom-field)
- [ProjectCustomField](/help/youtrack/devportal/api-concept-custom-fields.html#project-custom-field)
- [IssueCustomField](/help/youtrack/devportal/api-concept-custom-fields.html#issue-custom-field)
- [$type Mapping for Custom Fields](/help/youtrack/devportal/api-concept-custom-fields.html#type-issue-custom-fields)

Request Headers[Pagination](jetbrains__com__help__youtrack__devportal__api-concept-pagination.md)

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
