POST Category

The POST Category Incident Master API creates a new Category master record in the Incident Management (IM) module. Authorized administrators, integrations, and automation tools can create Category records directly without using the application UI.

Endpoint

POST /API/v1/Master/IM/Category

Note: Before creating a Category record, system retrieves its metadata to review required fields, supported fields, payload structure, constraints, and applicable endpoints. GET /API/v1/Master/IM/Category/metadata?sections=create.

curl --location 'https://<host>/API/v1/Master/IM/Category/metadata?sections=create' \
  --request GET \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: <API_KEY>'

Request Headers

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

Request Body Fields

Field	Data Type	Required	Description
`Active`	Boolean	No	Indicates whether the Category record is active.
`Text`	String	Yes	Display name or text value of the Category record.
`Is_Default`	Boolean	No	Indicates whether the Category is the default value.
`Is_Enabled_For_End_User`	Boolean or null	No	Indicates whether the Category is available to end users.
`Parent_Value`	Integer, string, or null	No	Parent Category reference, if applicable.
`Instance`	String	No	Instance or tenant associated with the Category record.

Sample Payload

{
  "Active": true,
  "Text": "Sample Category Name",
  "Is_Default": false,
  "Is_Enabled_For_End_User": true,
  "Parent_Value": 0,
  "Instance": "Info"
}

Sample Payload Field Details

Field Name	Sample Value	Data Type	Description
Active	`true`	Boolean	Indicates whether the Category record is active and available for use.
Text	`"Sample Category Name"`	String	Specifies the display name of the Category record.
Is_Default	`false`	Boolean	Indicates whether the Category functions as the default Category.
Is_Enabled_For_End_User	`true`	Boolean	Indicates whether the Category is available for selection by end users.
Parent_Value	`0`	Integer	Specifies the identifier of the parent Category. A value of `0` can represent a top-level Category, depending on the system configuration.
Instance	`"Info"`	String	Specifies the application instance associated with the Category record.

Sample Payload Explanation

Attribute	Value	Explanation
Active Status	`true`	Creates the Category as an active record that is available for use.
Category Name	`"Sample Category Name"`	Sets the display name of the new Category.
Default Status	`false`	Creates the Category as a non-default Category.
End-User Availability	`true`	Makes the Category available for selection by end users.
Parent Category	`0`	Associates the Category with the specified parent value. Confirm whether `0` represents a top-level Category in the target environment.
Application Instance	`"Info"`	Associates the Category with the specified application instance.

Note: While creating a Default category by setting Is_Default: true, only one default category must exist, setting more than one will return error.

Sample Request

curl --location 'https://<host>/API/v1/Master/IM/Category' \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <API_KEY>' \
  --data-raw '{
    "Active": true,
    "Text": "Sample Category Name",
    "Is_Default": false,
    "Is_Enabled_For_End_User": true,
    "Parent_Value": 0,
    "Instance": "Info"
  }'

Sample Request Details

Component	Value	Description
HTTP Method	`POST`	Creates a new Category master record.
Endpoint URL	`https://<host>/API/v1/Master/IM/Category`	API endpoint used to create a Category record.
Host	`<host>`	Base URL of the target environment, such as Development, Test, or Production.
API Version	`v1`	Identifies Version 1 of the API.
Resource Group	`Master`	Identifies the Master Data API resource group.
Module	`IM`	Identifies the Incident Management module.
Master Name	`Category`	Identifies the Category master entity.
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 data.
X-Api-Key Header	`<API_KEY>`	API key used to authenticate and approve the request.
Request Body	JSON payload	Contains the values used to create the Category record.

Request Body Details

Field Name	Sample Value	Data Type	Required	Description
Active	`true`	Boolean	Yes	Creates the Category as an active record.
Text	`"Sample Category Name"`	String	Yes	Sets the display name of the Category record.
Is_Default	`false`	Boolean	Yes	Specifies that the Category is not the default Category.
Is_Enabled_For_End_User	`true`	Boolean	Yes	Makes the Category available to end users.
Parent_Value	`0`	Integer	Yes	Specifies the identifier of the parent Category.
Instance	`"Info"`	String	Yes	Specifies the application instance associated with the Category.

Sample Request Explanation

Attribute	Submitted Value	Result
HTTP Operation	`POST`	Requests the creation of a new Category record.
Category Name	`"Sample Category Name"`	Creates the Category with the specified display name.
Active Status	`true`	Makes the new Category active.
Default Status	`false`	Does not configure the new Category as the default Category.
End-User Availability	`true`	Makes the new Category available for selection by end users.
Parent Category	`0`	Associates the new Category with the specified parent value.
Application Instance	`"Info"`	Associates the new Category with the specified application instance.

The request creates an active Category named Sample Category Name, makes the Category available to end users, does not set the Category as the default, and associates the Category with the specified parent value and application instance.

Sample Success Response

HTTP 201 Created

{
  "message": "Master record created successfully.",
  "data": {
    "success": true,
    "recordId": 17,
    "displayName": "Category",
    "moduleCode": "IM",
    "operation": "INSERT",
    "rowsAffected": 1
  },
  "executionTime": 0.0553389
}

A successful request creates the Category record and returns the generated record identifier and execution details.

Sample Success Response Field Details

Field Name	Sample Value	Data Type	Description
message	`"Master record created successfully."`	String	Confirms that the system created the Category record successfully.
data	Response object	Object	Contains details about the completed create operation.
data.success	`true`	Boolean	Indicates whether the Category create operation succeeded.
data.recordId	`17`	Integer	Unique identifier generated for the newly created Category record.
data.displayName	`"Category"`	String	Identifies the master entity created by the operation.
data.moduleCode	`"IM"`	String	Identifies the Incident Management module associated with the new record.
data.operation	`"INSERT"`	String	Indicates that the API performed an insert operation.
data.rowsAffected	`1`	Integer	Indicates the number of Category records created by the request.
executionTime	`0.0553389`	Number	Indicates the time taken to process the request, in seconds.

Sample Success Response Explanation

Response Attribute	Returned Value	Meaning
HTTP Status	`201 Created`	Indicates that the API successfully created a new resource.
Response Message	`"Master record created successfully."`	Confirms that the Category creation operation completed successfully.
Operation Status	`true`	Confirms that the API successfully created the Category record.
Generated Record ID	`17`	Identifies the newly created Category record.
Master Entity	`"Category"`	Confirms that the created record belongs to the Category master.
Module	`"IM"`	Confirms that the record belongs to the Incident Management module.
Operation	`"INSERT"`	Confirms that the API performed a create operation.
Rows Affected	`1`	Confirms that the operation created one Category record.
Execution Time	`0.0553389` seconds	Reports the time taken to process the create request.

A successful request returns HTTP 201 Created. The response confirms that the API created a new Category record, assigns the generated record ID 17, and indicates that the operation affected one record.

Error Responses

400 Bad Request

Returned when the payload is invalid, a required field is missing, or a supplied value fails validation.

{
  "message": "Invalid request payload.",
  "errorCode": 400,
  "details": "One or more fields failed validation."
}

401 Unauthorized

Returned when valid API credentials are not provided or have expired.

{
  "message": "Unauthorized access.",
  "errorCode": 401,
  "details": "Valid API credentials are required."
}

403 Forbidden

Returned when the authenticated client does not have permission to create Category records.

{
  "message": "You do not have permission to create master records.",
  "errorCode": 403,
  "details": "The authenticated user lacks the required privileges to perform this operation."
}

404 Not Found

Returned when the Category master entity does not exist or the endpoint URL is invalid.

{
  "message": "Master entity not found.",
  "errorCode": 404,
  "details": "The requested master entity or endpoint does not exist."
}

Documentation Index