# Custom Fields

This resource lets you work with the custom fields. In the old REST API we called them "prototypes".
|  Resource  |     ```GENERIC /api/admin/customFieldSettings/customFields ```    |
| --- | --- |
|  Returned entity  |  [CustomField](api-entity-CustomField.html). For the description of the entity attributes, see [Supported Fields](#CustomField-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of CustomFields](#get_all-CustomField-method).    * `POST`: [Add a New CustomField](#create-CustomField-method).    |
|  Supported sub-resources  |      * [/api/admin/customFieldSettings/customFields/{fieldID}](operations-api-admin-customFieldSettings-customFields.html)    * [/api/admin/customFieldSettings/customFields/{fieldID}/fieldDefaults](resource-api-admin-customFieldSettings-customFields-fieldID-fieldDefaults.html)    * [/api/admin/customFieldSettings/customFields/{fieldID}/instances](resource-api-admin-customFieldSettings-customFields-fieldID-instances.html)    |

## CustomField attributes

Represents a custom field in YouTrack.

### Related Resources

Below you can find the list of resources that let you work with this entity.

* [Custom Fields]()

### Attributes

This table describes attributes of the `CustomField` entity.

* To receive an attribute in the response from the server, specify it explicitly in the `fields` request parameter.

* To update an attribute, provide it in the body of a POST request.

|  Field  |  Type  |  Description  |
| --- | --- | --- |
|  id  |  String  |  The ID of the custom field. `Read-only`.  |
|  name  |  String  |  The name of the custom field.  |
|  localizedName  |  String  |  If set, then this value is used for the field presentation in UI. `Can be null`.  |
|  fieldType  |  [FieldType](api-entity-FieldType.html)  |  The type of the custom field.  |
|  isAutoAttached  |  Boolean  |  If `true`, then the field will be automatically attached to new projects.  |
|  isDisplayedInIssueList  |  Boolean  |  If `true`, the field is visible in the Issues list by default.  |
|  ordinal  |  Int  |  Number of the field.  |
|  aliases  |  String  |  A comma-separated list of aliases that can be used in search and commands. `Can be null`.  |
|  fieldDefaults  |  [CustomFieldDefaults](api-entity-CustomFieldDefaults.html)  |  Default project-related settings for the custom field. May contain different values for custom fields of different types. `Read-only`.  |
|  hasRunningJob  |  Boolean  |  Indicates whether a background job is running for this field. In this case, some field operations may be temporary unavailable. `Read-only`.  |
|  isUpdateable  |  Boolean  |  Indicates whether the current user has permissions to update this field. `Read-only`.  |
|  instances  |  [Array of ProjectCustomFields](api-entity-ProjectCustomField.html)  |  Project-related settings. May contain different values for custom fields of different types  |

## Read a List of CustomFields

Get all available custom fields in the system.

### Request syntax

```GENERIC
GET /api/admin/customFieldSettings/customFields?{fields}&{$top}&{$skip}
```

|  null  |  The database ID of CustomField  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of CustomField attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |
|  $skip  |  Int  |  Optional. Lets you set a number of returned entities to skip before returning the first one.  |
|  $top  |  Int  |     Optional. Lets you specify the maximum number of entries that are returned in the response. If you don't set the $top value, the server limits the maximum number of returned entries.       The server returns a maximum of 42 entries for most resources that return collections. For more information, see [Pagination](api-concept-pagination.html).     |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/admin/customFieldSettings/customFields?fields=id,name,fieldType(presentation,id)&$top=3
```

#### Sample response body

```JSON
[
  {
    "fieldType": {
      "presentation": "ownedField[1]",
      "id": "ownedField[1]",
      "$type": "FieldType"
    },
    "name": "Subsystem",
    "id": "58-0",
    "$type": "CustomField"
  },
  {
    "fieldType": {
      "presentation": "enum[1]",
      "id": "enum[1]",
      "$type": "FieldType"
    },
    "name": "Priority",
    "id": "58-1",
    "$type": "CustomField"
  },
  {
    "fieldType": {
      "presentation": "enum[1]",
      "id": "enum[1]",
      "$type": "FieldType"
    },
    "name": "Type",
    "id": "58-2",
    "$type": "CustomField"
  }
]
```

## Add a New CustomField

Create a new custom field in the system.

Required fields: `name`, `fieldType`.

For the list of available field type options, see [Type Mapping for Custom Fields](api-concept-custom-fields.html#type-issue-custom-fields). As you're creating a new custom field in the system, you're going to need a value from the Custom Field Type column. Check the sample request below for more details.

### Required permissions

Requires permissions: Update Project or Low-level Admin Write

### Request syntax

```GENERIC
POST /api/admin/customFieldSettings/customFields?{fields}
```

|  null  |  The database ID of CustomField  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of CustomField attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/admin/customFieldSettings/customFields?fields=id,name,fieldType(presentation,id)
```

#### Sample request body

```JSON
{
  "fieldType": {
    "id": "enum[1]"
  },
  "name": "Severity",
  "isDisplayedInIssueList": true,
  "isAutoAttached": false,
  "isPublic": true
}
```

#### Sample response body

```JSON
{
  "fieldType": {
    "presentation": "enum[1]",
    "id": "enum[1]",
    "$type": "FieldType"
  },
  "name": "Severity",
  "id": "58-22",
  "$type": "CustomField"
}
```