PUT Category

The PUT Category Incident Master API updates an existing Category master record in the Incident Management (IM) module. The request uses the target Category record's unique record ID, and the request payload contains the updated values for the record.

Use Case scenario	Solution
Rename an Incident Category	Update the `Text` field for the specified Category record.
Activate or deactivate a Category	Set `Active` to `true` or `false`.
Control end-user availability	Set `Is_Enabled_For_End_User` to control whether end users can access the Category.
Support configuration automation	Allow authorized integrations to update Category master data without using the application UI.

Update a Category Master Record

Endpoint

PUT /API/v1/Master/IM/Category/{recordId}

Updates an existing Category master record.

Path Parameters

Parameter	Data Type	Required	Description	Example
recordId	Integer	Yes	Unique identifier of the Category record to update.	1001

Fixed Path Values

Path Value	Description
IM	Module code for Incident Management.
Category	Master name for the Category entity.

Note: Before updating a Category record, system retrieves its metadata to review the expected payload structure and applicable fields. Metadata Endpoint GET /API/v1/Master/IM/Category/metadata?sections=update. The supplied Category reference specifies sections=updatefor retrieving the payload metadata used by this operation.

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Specifies the expected response format.
Content-Type	application/json	Yes	Indicates that the request body is JSON.
X-Api-Key	`<API_KEY>`	Yes	API key used to authenticate the request.

Request Body

Provide the Category values to update in JSON format.

Fields

Field Name	Description	Data Type	Required	Constraints	Example
Active	Indicates whether the Category record is active.	Boolean	Yes	Accepted values are `true` or `false`.	`true`
Text	Display name of the Category record.	String	Yes	Cannot be null or empty. Maximum supported length is 50 characters. Do not use unsupported special characters. Duplicate category names are not allowed.	"Hardware Issue"
Is_Enabled_For_End_User	Indicates whether the Category is available to end users in self-service and other end-user interfaces.	Boolean	Yes	Accepted values are `true` or `false`.	`false`

Sample Payload

{
  "Active": true,
  "Text": "Hardware Issue",
  "Is_Enabled_For_End_User": false
}

Sample Request

curl --location 'https://<host>/API/v1/Master/IM/Category/1001' \
--request PUT \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <API_KEY>' \
--data-raw '{
  "Active": true,
  "Text": "Hardware Issue",
  "Is_Enabled_For_End_User": false
}'

The sample request updates the Category record whose ID is 1001.

Component	Value	Description
HTTP Method	PUT	Updates an existing Category master record.
Endpoint URL	`https://<host>/API/v1/Master/IM/Category/1001`	API endpoint used to update the Category record with ID `1001`.
Host	`<host>`	Base URL of the target environment (for example, Development, Test, or Production).
Record ID	`1001`	Unique identifier of the Category record to update.
Accept Header	`application/json`	Indicates that the client expects the response in JSON format.
Content-Type Header	`application/json`	Indicates that the request body contains JSON format.
X-Api-Key Header	`<API_KEY>`	API key used to authenticate the request.
Request Body	JSON payload	Contains the Category values you must update.

Request Body Details

Field Name	Sample Value	Data Type	Description
Active	`true`	Boolean	Specifies whether the Category record is active.
Text	`Hardware Issue`	String	Display name of the Category.
Is_Enabled_For_End_User	`false`	Boolean	Specifies whether the Category is available to end users.

Example Explanation

The sample request performs the following actions:

Attribute	Updated Value	Result
Category Record ID	`1001`	Identifies the Category record to update.
Category Name	`Hardware Issue`	Updates the display name of the Category.
Active Status	`true`	Keeps the Category active.
End User Availability	`false`	Makes the Category unavailable to end users.

The request updates the Category record with ID 1001, changes its name to Hardware Issue, keeps the record active, and disables its availability for end users.

Sample Success Response

{
  "message": "Master record updated successfully.",
  "data": {
    "success": true,
    "recordId": 1001,
    "displayName": "Category",
    "moduleCode": "IM",
    "operation": "UPDATE",
    "rowsAffected": 1
  },
  "executionTime": 0.0117173
}

Response Fields

Field	Data Type	Description
message	String	Status message indicating the result of the operation.
success	Boolean	Indicates whether the update operation succeeded.
recordId	Integer	Identifier of the updated Category record.
displayName	String	Name of the master entity the update affected.
moduleCode	String	Module associated with the master record.
operation	String	Operation performed.
rowsAffected	Integer	Number of records updated.
executionTime	Number	Time taken to process the request in seconds.

Error Responses

400 Bad Request

Returned when the request payload is invalid, a required field is missing, or a field contains an unsupported value.

Validation Scenarios

Scenario	Description
Missing required field	The request omits the `Text` field or contains an empty value.
Invalid data type	A Boolean field contains a non-Boolean value.
Unsupported special characters	The Category name contains characters that are not supported by the application validation rules.
Category name exceeds max length	The `Text` value exceeds the max supported limit of 50 characters.
Duplicate category name	The updated Category name already exists and duplicates are not permitted.

Example: Missing Required Field

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid request payload.",
  "details": [
    "Text is required."
  ]
}

Example: Unsupported Special Characters

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid request payload.",
  "details": [
    "Category name contains unsupported special characters."
  ]
}

Example: Maximum Length Exceeded

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid request payload.",
  "details": [
    "Category name cannot exceed 50 characters."
  ]
}

Example: Duplicate Category Name

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid request payload.",
  "details": [
    "A category with the specified name already exists."
  ]
}

401 Unauthorized

Returned when the API key is missing or invalid.

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid or missing API credentials."
}

403 Forbidden

Returned when the authenticated client does not have permission to update the Category record.

{
  "status": 403,
  "error": "Forbidden",
  "message": "You do not have permission to perform this action."
}

404 Not Found

Returned when the specified Category record does not exist or the API endpoint URL is incorrect.

{
  "status": 404,
  "error": "Not Found",
  "message": "The specified master record was not found."
}

Documentation Index