Important
The improved Microsoft 365 Defender portal is now available. This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 Defender portal. Learn what’s new.
Applies to:
Important
Some information relates to prereleased product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
API description
Updates properties of existing incident. Updatable properties are: status, determination, classification, assignedTo, tags, and comments.
Quotas, resource allocation, and other constraints
- You can make up to 50 calls per minute or 1500 calls per hour before you hit the throttling threshold.
- You can set the
determinationproperty only ifclassificationis set to TruePositive.
If your request is throttled, it will return a 429 response code. The response body will indicate the time when you can begin making new calls.
Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Access the Microsoft 365 Defender APIs.
| Permission type | Permission | Permission display name |
|---|---|---|
| Application | Incident.ReadWrite.All | Read and write all incidents |
| Delegated (work or school account) | Incident.ReadWrite | Read and write incidents |
Note
When obtaining a token using user credentials, the user needs to have permission to update the incident in the portal.
HTTP request
PATCH /api/incidents/{id}
Request headers
| Name | Type | Description |
|---|---|---|
| Authorization | String | Bearer {token}. Required. |
| Content-Type | String | application/json. Required. |
Request body
In the request body, supply the values for the fields that should be updated. Existing properties that aren’t included in the request body will maintain their values, unless they have to be recalculated due to changes to related values. For best performance, you should omit existing values that haven’t changed.
| Property | Type | Description |
|---|---|---|
| status | Enum | Specifies the current status of the incident. Possible values are: Active, Resolved, and Redirected. |
| assignedTo | string | Owner of the incident. |
| classification | Enum | Specification of the incident. Possible values are: Unknown, FalsePositive, TruePositive. |
| determination | Enum | Specifies the determination of the incident. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, Other. |
| tags | string List | List of Incident tags. |
| comment | string | Comment to be added to the incident. |
Response
If successful, this method returns 200 OK. The response body will contain the incident entity with updated properties. If an incident with the specified ID wasn’t found, the method returns 404 Not Found.
Example
Request example
Here’s an example of the request.
PATCH https://api.security.microsoft.com/api/incidents/{id}
Response example
{
"status": "Resolved",
"assignedTo": "[email protected]",
"classification": "TruePositive",
"determination": "Malware",
"tags": ["Yossi's playground", "Don't mess with the Zohan"],
"comments": [
{
"comment": "pen testing",
"createdBy": "[email protected]",
"createdTime": "2021-05-02T09:34:21.5519738Z"
},
{
"comment": "valid incident",
"createdBy": "[email protected]",
"createdTime": "2021-05-02T09:36:27.6652581Z"
}
]
}