Updated on 2026-10-13 GMT+08:00

Updating Template Field Configurations

Function

This API is used to update the mandatory status and display status of template fields. The caller passes the field configuration list through the API. The system verifies and updates the is_required and is_visible attributes of the fields one by one.

Calling Method

For details, see Calling APIs.

Authorization Information

No identity policy-based permission required for calling this API.

URI

PUT /v2/projects/{project_id}/field-templates/{template_id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: 32-character UUID of a project, which uniquely identifies a project. Obtain the value of this parameter from the project_id field in the response body of the Querying the Project List API. Constraints: The value must contain 32 characters. Digits and letters are allowed. Value range: N/A Default value: N/A
template_id	Yes	String	Definition Template ID, which is obtained by calling the API for querying template field configurations. The value of template_id in the response body is the template ID. Constraints N/A Range N/A Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. Obtain a token by calling the IAM API for obtaining a user token. The value of X-Subject-Token in the response header is the user token. Constraints N/A Range The value contains 10 to 32,768 characters. Default Value N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
fields	Yes	Array of fields objects	Definition Field configuration list, which is used to update the mandatory and display status of fields in the template in batches. Constraints Array type. Each element contains the field, is_required, and is_visible attributes. Range N/A Default Value N/A

**Table 4** fields
Parameter	Mandatory	Type	Description
field	Yes	String	Definition Field ID, which specifies the field to be updated. Constraints N/A Range N/A Default Value N/A
is_required	No	Integer	Definition Whether a field is mandatory. Constraints The value can be 0 or 1. Range 0: optional 1: mandatory Default Value 0
is_visible	No	Boolean	Definition Whether the field is displayed. Constraints The value can be true or false. Range true: displayed false: hidden Default Value true

Response Parameters

Status code: 200

**Table 5** Response body parameters
Parameter	Type	Description
success	Boolean	Definition Whether the request is successful. Range true: success. false: failure.
error_configs	Array of error_configs objects	Definition Information about the field template that fails to be updated. Range N/A

**Table 6** error_configs
Parameter	Type	Description
field	String	Definition Field name. Range N/A
field_type	String	Definition Field type. Range N/A
is_visible	Boolean	Definition Visible or not. Range N/A
is_required	Integer	Definition Mandatory or not. Range N/A
error_message	String	Definition Error information. Range N/A

Status code: 400

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Requests

Updating template field configurations

PUT https://{endpoint}/v2/projects/a6a33eca679b435b85574bd2fde46ce7/field-templates/384006

{
  "fields" : [ {
    "field" : "developer",
    "is_required" : 1,
    "is_visible" : true
  }, {
    "field" : "custom_field16",
    "is_required" : 0,
    "is_visible" : true
  }, {
    "field" : "status_id",
    "is_required" : 0,
    "is_visible" : true
  } ]
}

Example Responses

Status code: 200

{
  "success" : false,
  "error_configs" : [ {
    "field" : "assigned_to_id",
    "field_type" : "select",
    "is_required" : 1,
    "error_message" : "System field is_required cannot be changed."
  } ]
}

Status Codes

Status Code	Description
200	Response to a successful request for updating template field configurations.
400	Response to an interface request failure.

Error Codes

See Error Codes.

Parent topic: Scrum Project Settings