# Project Custom Fields

This resource lets you access and configure custom fields in the specific project.
|  Resource  |     ```GENERIC /api/admin/projects/{projectID}/customFields ```    |
| --- | --- |
|  Returned entity  |  [ProjectCustomField](api-entity-ProjectCustomField.html). For the description of the entity attributes, see [Supported Fields](#ProjectCustomField-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of ProjectCustomFields](#get_all-ProjectCustomField-method).    * `POST`: [Add a New ProjectCustomField](#create-ProjectCustomField-method).    |

## ProjectCustomField attributes

Represents settings for custom fields in a particular project.

### Related Resources

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

* [Project Custom Fields](resource-api-admin-customFieldSettings-customFields-fieldID-instances.html)

### Attributes

This table describes attributes of the `ProjectCustomField` 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 project custom field. `Read-only`.  |
|  field  |  [CustomField](api-entity-CustomField.html)  |  The custom field in the project. `Read-only`. `Can be null`.  |
|  project  |  [Project](api-entity-Project.html)  |  The project where the custom field belongs. `Read-only`. `Can be null`.  |
|  canBeEmpty  |  Boolean  |  If `true`, the custom field can have empty value, otherwise `false`.  |
|  emptyFieldText  |  String  |  The text that is shown as a placeholder when the custom field has an empty value. `Can be null`.  |
|  ordinal  |  Int  |  The position number of this field on the list of project custom fields.  |
|  isPublic  |  Boolean  |  If `true`, the basic Read Issue and Update Issue permissions are sufficient to access this field. If `false`, the Read Issue Private Fields and Update Issue Private Fields permissions are required.  |
|  hasRunningJob  |  Boolean  |  If `true`, there is a background job running for this field. In this case, some field operations may be temporary inaccessible. `Read-only`.  |
|  condition  |  [CustomFieldCondition](api-entity-CustomFieldCondition.html)  |  The condition for showing the custom field. `Can be null`.  |

## Read a List of ProjectCustomFields

Read the list of custom fields that are attached to a specific project.

### Request syntax

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

|  null  |  The database ID of ProjectCustomField  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of ProjectCustomField 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/projects/0-0/customFields?$top=5&fields=id,field(name,fieldType($type)),project(shortName),canBeEmpty,isPublic
```

#### Sample response body

```JSON
[
  {
    "field": {
      "fieldType": {
        "$type": "FieldType"
      },
      "name": "Subsystem",
      "$type": "CustomField"
    },
    "project": {
      "shortName": "NP",
      "$type": "Project"
    },
    "canBeEmpty": true,
    "isPublic": true,
    "id": "82-8",
    "$type": "OwnedProjectCustomField"
  },
  {
    "field": {
      "fieldType": {
        "$type": "FieldType"
      },
      "name": "Priority",
      "$type": "CustomField"
    },
    "project": {
      "shortName": "NP",
      "$type": "Project"
    },
    "canBeEmpty": true,
    "isPublic": true,
    "id": "82-9",
    "$type": "EnumProjectCustomField"
  },
  {
    "field": {
      "fieldType": {
        "$type": "FieldType"
      },
      "name": "Type",
      "$type": "CustomField"
    },
    "project": {
      "shortName": "NP",
      "$type": "Project"
    },
    "canBeEmpty": false,
    "isPublic": true,
    "id": "82-10",
    "$type": "EnumProjectCustomField"
  },
  {
    "field": {
      "fieldType": {
        "$type": "FieldType"
      },
      "name": "State",
      "$type": "CustomField"
    },
    "project": {
      "shortName": "NP",
      "$type": "Project"
    },
    "canBeEmpty": false,
    "isPublic": true,
    "id": "82-11",
    "$type": "StateProjectCustomField"
  },
  {
    "field": {
      "fieldType": {
        "$type": "FieldType"
      },
      "name": "Fix versions",
      "$type": "CustomField"
    },
    "project": {
      "shortName": "NP",
      "$type": "Project"
    },
    "canBeEmpty": true,
    "isPublic": true,
    "id": "82-12",
    "$type": "VersionProjectCustomField"
  },
  {
    "field": {
      "fieldType": {
        "$type": "FieldType"
      },
      "name": "Assignee",
      "$type": "CustomField"
    },
    "project": {
      "shortName": "NP",
      "$type": "Project"
    },
    "canBeEmpty": true,
    "isPublic": true,
    "id": "84-111",
    "$type": "UserProjectCustomField"
  }
]
```

## Add a New ProjectCustomField

Attach the custom field to the project.

Required fields: `field` (`id`) – the database ID of the CustomField prototype that you're attaching to the project, `$type` – the type of the ProjectCustomField that YouTrack will create as the result of this request. For the mapping between the prototype field type and the `ProjectCustomField` $type, see [Type Mapping for Custom Fields](https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/api-concept-custom-fields.html#type-issue-custom-fields).

### Required permissions

Requires permissions: Update Project

### Request syntax

```GENERIC
POST /api/admin/projects/{projectID}/customFields?{fields}
```

|  null  |  The database ID of ProjectCustomField  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of ProjectCustomField 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/projects/81-1/customFields?fields=field(fieldType(valueType,id),name,id)
```

#### Sample request body

```JSON
{
  "field": {
    "name": "Last message related emails",
    "id": "46-21",
    "$type": "CustomField"
  },
  "$type": "SimpleProjectCustomField"
}
```

#### Sample response body

```JSON
{
  "field": {
    "fieldType": {
      "valueType": "string",
      "id": "string",
      "$type": "FieldType"
    },
    "name": "Last message related emails",
    "id": "46-21",
    "$type": "CustomField"
  },
  "$type": "SimpleProjectCustomField"
}
```