Edit

Share via

Update incidents API

  • Article

Applies to:

Note

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.

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

  1. You can make up to 50 calls per minute or 1,500 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 returns a 429 response code. The response body indicates 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 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

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 maintain their values, unless they have to be recalculated due to changes to related values. For best performance, you should omit existing values that didn't change.

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 (True positive), InformationalExpectedActivity (Informational, expected activity), and FalsePositive (False Positive).
determination Enum Specifies the determination of the incident.

Possible determination values for each classification are:

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

    Note

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

    Response

    If successful, this method returns 200 OK. The response body contains 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}

    Request data example

    {
    "status": "Resolved",
    "assignedTo": "secop2@contoso.com",
    "classification": "TruePositive",
    "determination": "Malware",
    "tags": ["Yossi's playground", "Don't mess with the Zohan"],
    "comment": "pen testing"
}

    Tip

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