Update incidents API


Want to experience Microsoft Defender XDR? Learn more about how you can evaluate and pilot Microsoft Defender XDR.

Applies to:


Try our new APIs using MS Graph security API. Find out more at: Use the Microsoft Graph security API - Microsoft Graph | Microsoft Learn. For information about the new update incident API using MS Graph security API, see Update incident.


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

  1. You can make up to 50 calls per minute or 1500 calls per hour before you hit the throttling threshold.
  2. You can set the determination property only if classification is 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.


One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Access the Microsoft Defender XDR 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


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, InProgress, and Redirected.
assignedTo string Owner of the incident.
classification Enum Specification of the incident. Possible values are: TruePositive, Informational, expected activity, and FalsePositive.
determination Enum Specifies the determination of the incident.

Possible determination values for each classification are:

  • True positive: Multistage attack (MultiStagedAttack), Malicious user activity (MaliciousUserActivity), Compromised account (CompromisedUser) – consider changing the enum name in public api accordingly, Malware (Malware), Phishing (Phishing), Unwanted software (UnwantedSoftware), and Other (Other).
  • Informational, expected activity: Security test (SecurityTesting), Line-of-business application (LineOfBusinessApplication), Confirmed activity (ConfirmedUserActivity) - consider changing the enum name in public api accordingly, and Other (Other).
  • False positive: Not malicious (Clean) - consider changing the enum name in public api accordingly, Not enough data to validate (InsufficientData), and Other (Other).
  • tags string list List of Incident tags.
    comment string Comment to be added to the incident.


    Around August 29, 2022, previously supported alert determination values ('Apt' and 'SecurityPersonnel') will be deprecated and no longer available via the API.


    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.


    Request example

    Here's an example of the request.

     PATCH https://api.security.microsoft.com/api/incidents/{id}

    Response example

        "status": "Resolved",
        "assignedTo": "secop2@contoso.com",
        "classification": "TruePositive",
        "determination": "Malware",
        "tags": ["Yossi's playground", "Don't mess with the Zohan"],
        "comments": [
                  "comment": "pen testing",
                  "createdBy": "secop2@contoso.com",
                  "createdTime": "2021-05-02T09:34:21.5519738Z"
                  "comment": "valid incident",
                  "createdBy": "secop2@contoso.comt",
                  "createdTime": "2021-05-02T09:36:27.6652581Z"


    Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender XDR Tech Community.