The GET Category Incident Master API retrieves Category master data from the Incident Management (IM) module. The API response matches the Category records displayed in the UI.
The API supports the following operations:
Retrieve List of Category Master Records
This endpoint retrieves all Category master records configured in the Incident Management module. Administrators, integrations, and automation tools can use the endpoint for configuration review, validation, and reporting.
Endpoint
GET /API/v1/Master/IM/CategoryComponent | Value | Description |
|---|---|---|
HTTP Method | GET | Retrieves data from the server. The Operation is read-only and does not create, update, or delete records. |
API | API | Stands for Application Programming Interface. It provides a standard way for applications to communicate with the system and exchange data. |
Version | v1 | Indicates Version 1 of the API. Versioning helps maintain compatibility when developers introduce new API versions. |
Resource Group | Master | Refers to the Master Data module, which contains reusable reference data such as Categories, Priorities, Statuses, and Locations. |
Module | IM | Stands for Incident Management. It identifies that the requested master data belongs to the Incident Management module. |
Resource | Category | Specifies the Category master data resource to retrieve. Categories classify Incident records. |
Request Headers
{
"Accept": "application/json",
"X-Api-Key": "<API_KEY>"
}Header | Value | Required | Description |
|---|---|---|---|
Accept | application/json | Yes | Requests the API to return the response in JSON format. |
X-Api-Key | <API_KEY> | Yes | API key for authentication and authorization. |
Sample Request
The following cURL request sends an HTTP GET request to retrieve all Category master records. The request includes the Accept header to specify JSON as the expected response format and the x-API-header to authenticate the caller.
Replace with a valid API key before sending the request. Replace {host} with the appropriate server address when calling the API from another environment.
curl --location '{host}/API/v1/Master/IM/Category' \
--request GET \
--header 'Accept: application/json' \
--header 'X-Api-Key: <API_KEY>'Sample Response
The following sample response returns an array of Category master records. Each object in the array represents one Category configured in the Incident Management module.
In this response, the API returns Category record names such as Hardware Issue, Software Issue. The record can be uniquely identified using the record ID 1001 and 1002. The first object has isDefault set to true, meaning the system uses this Category as the default Category across Incident Management and automatically populates this value in the Category field. In the second object, isDefault is false, meaning the category value appears in the Category field dropdown for users to select in the form. The isEnabledForEndUser value is also true, which means end users using the Incident form can view and select it. The parentValue is null, indicating that this Category is a top-level Category which is not associated with a parent Category.
[
{
"recordId": 1001,
"text": "Hardware Issue",
"isDefault": true,
"isEnabledForEndUser": true,
"parentValue": null
},
{
"recordId": 1002,
"text": "Software Issue",
"isDefault": false,
"isEnabledForEndUser": true,
"parentValue": null
}
]Response Fields
The Category master list exposes the following fields:
Field | Type | Example Value | Description |
|---|---|---|---|
Value | Integer | 1001 | Unique value or identifier of the Category record. |
Text | String | "Hardware Issue" | Display name of the Category. |
Active | Boolean | true | Indicates whether the Category record is active and available for use. |
Parent_Value | Integer or Null | null | Value of the parent Category, if applicable. A value of null indicates that the Category does not have a parent Category. |
Instance | Integer | 1 | Unique identifier of the instance associated with the Category. |
Instance_Text | String | "Production" | Display name of the instance associated with the Category. |
Business Use Cases
Scenario | Resolution |
|---|---|
An integration needs valid Category values before creating or updating an Incident. | Call the GET Category Incident Master API to retrieve the configured Category records. Use the returned Category identifier in the Incident create or update request. |
An external system stores Category mappings for Incident synchronization. | Call the API to retrieve the latest Category master records and synchronize them with the external system’s mapping table. |
An automated process receives an Incident Category name but requires its unique identifier. | Retrieve the Category master list, locate the record with the matching Category name, and use its Value in the next Incident API request. |
A scheduled integration must keep Category reference data up to date. | Call the API at scheduled intervals and compare the response with the Category records stored in the consuming system. Add, update, or deactivate mappings as required. |
An integration must verify a Category before submitting an Incident request. | Call the API and confirm that the Category exists and that its Active value is true. This prevents the integration from submitting an invalid or inactive Category. |
An integration must identify the parent of a Category. | Use the Parent_Value returned in the response to determine the Category hierarchy and apply the appropriate parent-child mapping. |
You are migrating incident data from another system. | Retrieve all valid Category records and map the source-system Category values to the corresponding Category identifiers before migrating the Incident records. |
An integration supports many application instances. | Use the Instance and Instance_Text values to associate each Category with the correct instance during synchronization or Incident processing. |
Expected Result
Returns HTTP 200 OK.
Returns all available Category master records configured for Incident Management.
Returns details for each Category, including the record ID, Category name, default settings, manual-close override setting, end-user availability, and parent Category value.
Sample Expected Result
The API successfully retrieves the list of Category master records configured for Incident Management.
[
{
"recordId": 1001,
"masterName": "Category",
"text": "Hardware Issue",
"im_Manual_Close_Override": false,
"is_Default": true,
"is_Default_For_PM": false,
"is_Enabled_For_End_User": true,
"parent_Value": null
},
{
"recordId": 1002,
"masterName": "Category",
"text": "Software Issue",
"im_Manual_Close_Override": false,
"is_Default": false,
"is_Default_For_PM": false,
"is_Enabled_For_End_User": true,
"parent_Value": null
}
]Retrieve Category Master Record Details
This endpoint retrieves the details of a specific Category master record by using its unique record ID.
Endpoint
GET /API/v1/Master/IM/Category/{recordId}Component | Value | Description |
|---|---|---|
HTTP Method | GET | Retrieves data from the server. Read-only; does not create, update, or delete records. |
API | API | Stands for Application Programming Interface. It provides a standard way for applications to communicate with the system and exchange data. |
Version | v1 | Indicates Version 1 of the API. Versioning helps maintain compatibility when we introduce new API versions. |
Resource Group | Master | Refers to the Master Data module, which contains reusable reference data such as Categories, Priorities, Statuses, and Locations. |
Module | IM | Stands for Incident Management. It identifies that the requested master data belongs to the Incident Management module. |
Resource | Category | Specifies the Category master data resource to retrieve. |
Record Identifier | {recordId} | The unique identifier of the Category record to retrieve. Replace this placeholder with an actual record ID, such as 1001. |
Path Parameter
Parameter | Type | Required | Description |
|---|---|---|---|
recordId | Integer | Yes | Unique identifier of the Category master record. |
Request Headers
{
"Accept": "application/json",
"X-Api-Key": "<API_KEY>"
}Header | Value | Required | Description |
|---|---|---|---|
Accept | application/json | Yes | Requests the API to return the response in JSON format. |
X-Api-Key | <API_KEY> | Yes | Provide the API key to authenticate the caller and grant access to the endpoint. |
Sample Request
The following request retrieves the Category master record with the record ID 1001. You supply the recordId as a path parameter in the endpoint URL to identify the specific Category record to retrieve.
Use this request when an integration or automated process needs to retrieve the configuration details of a known Category record.
Replace 1001 with the record ID of the Category that you want to retrieve. Replace <API_KEY> with a valid API key before sending the request. Replace {host} with the appropriate server address when calling the API from another environment.
curl --location '{host}/API/v1/Master/IM/Category/1001' \
--request GET \
--header 'Accept: application/json' \
--header 'X-Api-Key: <API_KEY>'Sample Response
The response returns the Category master record whose recordId matches the value specified in the request URL.
{
"recordId": 1001,
"masterName": "Category",
"text": "Hardware Issue",
"im_Manual_Close_Override": false,
"is_Default": true,
"is_Default_For_PM": false,
"is_Enabled_For_End_User": true,
"parent_Value": null
}In this example, the API returns the Category named Hardware Issue with the following configuration:
Field | Value | Description |
|---|---|---|
recordId | 1001 | Uniquely identifies the Category record. |
masterName | Category | Identifies the master data type. |
text | Hardware Issue | Specifies the name of the Category. |
im_Manual_Close_Override | false | Indicates that the manual-close override option is not enabled for this Category. Any Incident closure restrictions configured in the system continue to apply. |
is_Default | true | Indicates that this Category serves as the default Category for Incident Management. |
is_Default_For_PM | false | Indicates that this Category does not serve as the default Category for Problem Management. |
is_Enabled_For_End_User | true | Indicates that this Category is available for use in end-user Incident operations. |
parent_Value | null | Indicates that this Category is not linked to a parent Category. |
An integration can use these values to verify the configuration of the Category before using its recordId in another Incident Management API request.
Note
The im_Manual_Close_Override field shows whether the Category enables the manual-close override option. An integration can check this value before initiating or validating a manual Incident closure. The value does not close an Incident by itself. It only describes the Category configuration.
Use this response when you need the details of a specific Category record, such as verifying default settings, end-user visibility, or parent-category relationships for a known record ID.
Business Use Cases
Scenario | Resolution |
|---|---|
An external system receives an Incident that contains a Category record ID. | Retrieve the specific Category record to get its name and configuration before processing or synchronizing the Incident. |
An integration must check a Category before creating or updating an Incident. | Retrieve the Category by recordId and verify the intended Category before including the identifier in the Incident request. |
A synchronization process detects that one Category record has changed. | Retrieve only the affected Category record and update its mapping in the target system without retrieving the complete Category master list. |
An Incident imported from another system contains an existing Category mapping. | Retrieve the mapped Category record to confirm that the stored record ID still corresponds to the expected Category. |
An automated workflow must apply rules based on a Category’s configuration. | Retrieve the Category record and check its default, manual-close override, end-user availability, and parent Category settings before continuing the workflow. |
A reporting system contains an Incident Category ID but not its descriptive name. | Retrieve the Category record and use its text value to associate the Category name with the ID in reports or exported data. |
An integration must identify the hierarchy of a known Category. | Retrieve the Category record and check parent_Value to determine whether the Category belongs to a parent Category. |
A Category mapping fails during Incident processing. | Retrieve the Category using the mapped recordId and compare the returned values with the mapping stored in the external system to identify the mismatch. |
Expected Result
Returns HTTP 200 OK.
Returns the Category master record that matches the specified recordId.
Returns the record ID, Category name, default settings, manual-close override setting, end-user availability, and parent Category value.
Sample Expected Result
The API successfully retrieves the Category record with the record ID 1001.
{
"recordId": 1001,
"masterName": "Category",
"text": "Hardware Issue",
"im_Manual_Close_Override": false,
"is_Default": true,
"is_Default_For_PM": false,
"is_Enabled_For_End_User": true,
"parent_Value": null
}Error Responses
401 Unauthorized
Returned when the request does not include a valid API key or the caller does not have authenticated access.
The following request does not include the required X-Api-Key header:
curl --location '{host}/API/v1/Master/IM/Category' \
--request GET \
--header 'Accept: application/json'{
"message": "Unauthorized",
"errorCode": 401,
"details": "Valid API credentials are required."
}404 Not Found
Returned when the requested Category record ID does not exist or the endpoint path is incorrect.
The following request attempts to retrieve a Category with the record ID 9999:
curl --location '{host}/API/v1/Master/IM/Category/9999' \
--request GET \
--header 'Accept: application/json' \
--header 'X-Api-Key: {API_KEY}'{
"message": "Record not found",
"errorCode": 404,
"details": "The requested Category record was not found."
}