Querying Customized Fields of Scrum Work Items

Updated on 2025-05-22 GMT+08:00

View PDF

Function

Queries the optional list of customized fields of the Scrum work item. All fields that meet the custom_fields or names condition are returned. If neither of the two values is transferred, the list of all customized fields is returned.

URI

POST /v4/projects/{project_id}/issues/custom-fields

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Specifies the 32-bit ID of the devcloud project.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Specifies the user token. It can be obtained by calling an IAM API. The value of X-Subject-Token in the response header is the user token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
custom_fields	No	Array of strings	Custom Parameter
names	No	Array of strings	Meanings displayed on the customized field page
included_not_in_use	No	Boolean	Indicates whether the query result contains unused user-defined fields. By default, only user-defined fields in use are queried. If this parameter is set to true, all user-defined fields in the project are queried.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
datas	Array of IssueCustomField objects	Data Returned by Customized Fields

**Table 5** IssueCustomField
Parameter	Type	Description
name	String	Custom Parameter
custom_field	String	Custom Parameter
options	String	Optional values of a customized field. Use commas (,) to separate multiple values.
type	String	User-defined field type, textArea: multi-line text, which can contain only Chinese characters, uppercase letters, lowercase letters, digits, underscores (), and hyphens (-) and cannot exceed 500 characters. text: single-line text, which can contain only Chinese characters, uppercase letters, lowercase letters, digits, underscores (), and hyphens (-) and cannot exceed 500 characters. The select drop-down list box can contain only Chinese characters, uppercase letters, lowercase letters, digits, underscores (), and hyphens (-). Each option can contain a maximum of 40 characters. A maximum of 60 options can be defined. number: The value range is set when a user creates a customized field. The value of date is accurate to year, month, and day, and the value of time_date is accurate to hour, minute, and second. The value is a long integer timestamp. The check box can contain only Chinese characters, uppercase letters, lowercase letters, digits, underscores (), and hyphens (-). Each option can contain a maximum of 40 characters. A maximum of 60 options can be defined. The radio option button can contain only Chinese characters, uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-). Each option can contain a maximum of 40 characters. A maximum of 60 options can be defined.
tracker_ids	Array of integers	Work item types supported by user-defined fields: 2 task/task, 3 defect /Bug,5Epic,6Feature,7Story
create_time	String	Time when a customized field is created.

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_msg	String	Description
error_code	String	Error Codes

Status code: 401

**Table 7** Response body parameters
Parameter	Type	Description
error_msg	String	Description
error_code	String	Error Codes

Example Requests

Post https://{endpoint}/v4/projects/0792b7d26cb74bd799cbae80063dc74a/issues/custom-fields

{
  "names" : [ "Drop-down list box demo" ],
  "included_not_in_use" : true
}

Example Responses

Status code: 200

{
  "datas" : [ {
    "name" : "selectName",
    "custom_field" : "custom_field16",
    "options" : "selectName1,selectName2",
    "type" : "ratio",
    "tracker_ids" : [ 7 ],
    "create_time" : "2023-05-17T09:50:04+08:00"
  } ]
}