PUT Priority Matrix

The PUT Priority Matrix Incident Master API updates an existing Priority Matrix configuration in the Incident Management (IM) module. The matrix maps an Impact and Urgency combination to a Priority value. Authorized administrators, integrations, and automation tools can update this mapping without using the application UI.

Use Case scenarios	Solution
Change the calculated Incident Priority	Update `Priority` for the applicable Impact and Urgency combination.
Activate or deactivate a matrix mapping	Set `Active` to `true` or `false`.
Correct an Impact and Urgency mapping	Supply the applicable `Impact`, `Urgency`, and `Priority` identifiers.
Update an instance-specific mapping	Use `Instance` to identify the applicable tenant or configuration context.
Support configuration automation	Allow authorized integrations to update Priority Matrix mappings programmatically.

Endpoint

PUT /API/v1/Master/IM/PriorityMatrix

Note
The supplied endpoint does not include a {recordId} path parameter. The values and context in the request payload identify the target mapping.

Endpoint Details

Path Value	Description
`IM`	Module code for Incident Management.
`PriorityMatrix`	Master entity containing Impact, Urgency, and Priority mappings.

Before updating a Priority Matrix, system retrieves its update metadata to review required fields, supported fields, payload structure, validation constraints, and applicable endpoint. GET /API/v1/Master/IM/PriorityMatrix/metadata?sections=update.

Sample Metadata Request

curl --location 'https://<host>/API/v1/Master/IM/PriorityMatrix/metadata?sections=update' \
  --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	Yes	Indicates whether the Priority Matrix mapping is active.
`Impact`	Integer	Yes	Identifier of the Impact value used in the mapping.
`Urgency`	Integer	Yes	Identifier of the Urgency value used in the mapping.
`Priority`	Integer	Yes	Identifier of the Priority assigned to the Impact and Urgency combination.
`Instance`	String	Yes	Instance or tenant associated with the Priority Matrix mapping.

Sample Payload

{
  "Active": true,
  "Impact": 0,
  "Urgency": 0,
  "Priority": 0,
  "Instance": "Info"
}

Sample Payload Field Details

Field Name	Sample Value	Data Type	Description
Active	`true`	Boolean	Indicates whether the Priority Matrix mapping is active and available for use.
Impact	`0`	Integer	Specifies the identifier of the Impact value associated with the Priority Matrix mapping.
Urgency	`0`	Integer	Specifies the identifier of the Urgency value associated with the Priority Matrix mapping.
Priority	`0`	Integer	Specifies the identifier of the Priority value assigned to the Impact and Urgency combination.
Instance	`"Info"`	String	Specifies the application instance associated with the Priority Matrix mapping.

Sample Payload Explanation

Attribute	Value	Explanation
Active Status	`true`	Keeps the Priority Matrix mapping active and available for use.
Impact Identifier	`0`	Associates the mapping with the Impact record identified by `0`.
Urgency Identifier	`0`	Associates the mapping with the Urgency record identified by `0`.
Priority Identifier	`0`	Assigns the Priority record identified by `0` to the specified Impact and Urgency combination.
Application Instance	`"Info"`	Associates the Priority Matrix mapping with the specified application instance.

Note: The sample values are illustrative. Replace the Impact, Urgency, and Priority values with valid identifiers configured in the target environment. Confirm the expected value and data type for Instance from the Priority Matrix metadata.

Sample Request

curl --location 'https://<host>/API/v1/Master/IM/PriorityMatrix' \
  --request PUT \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <API_KEY>' \
  --data-raw '{
    "Active": true,
    "Impact": 0,
    "Urgency": 0,
    "Priority": 0,
    "Instance": "Info"
  }'

Sample Request Details

Component	Value	Description
HTTP Method	`PUT`	Updates an existing Priority Matrix mapping.
Endpoint URL	`https://<host>/API/v1/Master/IM/PriorityMatrix`	API endpoint used to update the Priority Matrix mapping.
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	`PriorityMatrix`	Identifies the Priority Matrix 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 Impact, Urgency, Priority, status, and instance values for the Priority Matrix mapping.

Request Body Details

Field Name	Sample Value	Data Type	Required	Description
Active	`true`	Boolean	Yes	Keeps the Priority Matrix mapping active and available for use.
Impact	`0`	Integer	Yes	Identifies the Impact value associated with the mapping.
Urgency	`0`	Integer	Yes	Identifies the Urgency value associated with the mapping.
Priority	`0`	Integer	Yes	Identifies the Priority value assigned to the Impact and Urgency combination.
Instance	`"Info"`	String	Yes	Identifies the application instance associated with the mapping.

Sample Request Explanation

Attribute	Updated Value	Result
Active Status	`true`	Keeps the Priority Matrix mapping active.
Impact Identifier	`0`	Updates the Impact value associated with the mapping.
Urgency Identifier	`0`	Updates the Urgency value associated with the mapping.
Priority Identifier	`0`	Assigns the specified Priority value to the Impact and Urgency combination.
Application Instance	`"Info"`	Associates the Priority Matrix mapping with the specified application instance.

The request updates the Priority Matrix mapping for the specified Impact and Urgency combination, assigns the corresponding Priority value, keeps the mapping active, and associates it with the specified application instance.

Sample Success Response

HTTP 200 OK

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

Sample Success Response Field Details

Field Name	Sample Value	Data Type	Description
message	`"Master record updated successfully."`	String	Provides a message confirming that the Priority Matrix mapping updated successfully.
data	Response object	Object	Contains details about the completed update operation.
data.success	`true`	Boolean	Indicates whether the Priority Matrix update operation succeeded.
data.recordId	`1001`	Integer	Identifies the Priority Matrix record updated by the request.
data.displayName	`"PriorityMatrix"`	String	Identifies the master entity the request updated.
data.moduleCode	`"IM"`	String	Identifies the Incident Management module associated with the updated record.
data.operation	`"UPDATE"`	String	Identifies the operation performed on the Priority Matrix record.
data.rowsAffected	`1`	Integer	Indicates the number of Priority Matrix records updated by the request.
executionTime	`0.0117173`	Number	Indicates the time taken to process the request, in seconds.

Sample Success Response Explanation

Response Attribute	Returned Value	Meaning
HTTP Status	`200 OK`	Indicates that the API successfully processed the request.
Response Message	`"Master record updated successfully."`	Confirms that the master record update completed successfully.
Operation Status	`true`	Confirms that the Priority Matrix update operation succeeded.
Updated Record ID	`1001`	Identifies the Priority Matrix record affected by the request.
Master Entity	`"PriorityMatrix"`	Confirms that the updated record belongs to the Priority Matrix master.
Module	`"IM"`	Confirms that the record belongs to the Incident Management module.
Operation	`"UPDATE"`	Confirms that the API performed an update operation.
Rows Affected	`1`	Confirms that the update operation affected one Priority Matrix record.
Execution Time	`0.0117173` seconds	Reports the time taken to process the update request.

A successful request returns HTTP 200 OK. The response confirms that the API successfully updated the Priority Matrix mapping, identifies the updated record as 1001, and confirms that the operation affected one record.

Error Responses

400 Bad Request

Returned when a required field is missing, a referenced value is invalid, or the payload does not match the expected schema.

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid request payload.",
  "details": [
    "Impact must reference a valid Impact value.",
    "Urgency must reference a valid Urgency value.",
    "Priority must reference a valid Priority value."
  ]
}

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

Documentation Index