Get Incidents‎

POST /Command/GetIncidents

Gets a list of filtered incidents with specified fields.

Request

Authentication: API keys or JSON web tokens (JWT)

Body Parameters

Parameter Name	Type	Required/Optional	Description
Username	`string`	Required	The username of the D3 SOAR user account making the request.
Site	`string`	Required	The D3 SOAR site containing the desired incidents to retrieve with the request.
Filter	`array<array<JSON Object>>`	Optional	The list of criteria, each containing one or more JSON object conditions, used to filter incidents. The "field" key points to an incident field. The "operator" key is the condition operator that establishes the logical relationship between the field and the value. The supported operators are: ["<", ">", "=", "<=", ">=", "!=", "LIKE", "IS EMPTY", and "IS NOT EMPTY"]. The "value" key is the data or criterion that the field is compared against. The "section" key is optional. When included in a condition, filtering will use Dynamic Fields instead of Static Fields. The "field" property must be assigned a value that matches the name of an Activity or Info Activity UI block under the specified section in the Incident Form Editor. The "AND" logic applies between JSON objects within the same array, whereas the "OR" logic applies between different arrays. For non-dynamic "field" values, refer to the sample data for the following Static Fields input parameter.
Static Fields	`array<string>`	Optional	The static incident fields to be included in the results. Default fields will be selected for each resulting incident if the Static Fields input is left empty. For D3 vSOC versions earlier than 16.8, default fields are all those in the sample data except for "Incident Raw Data" and "Event Raw Data." For D3 vSOC versions 16.8 and later, default fields are all those in the sample data except for "Date Closed," "Closed by," "Incident Raw Data" and "Custom Field." In these later versions, the "Playbook" static field returns playbooks that have either been completed or stopped due to an error. The static fields "Date Created," "Date Modified" and "Date Closed" are in UTC time.
Dynamic Fields	`JSON Object`	Optional	The dynamic incident fields to be included in the results. A key in the JSON object is the user-specified Section name of a dynamic field (i.e. incident form). The value (string array) corresponding to a key is the user-specified Activity or Info Activity name within the section.
Start Time	`string`	Required	The start time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.
End Time	`string`	Required	The end time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.
Output Format	`integer`	Optional	Allows users to choose the format in which to present incident data. Available options are: 1 (CSV) 2 (JSON) 3 (CSV link) 4 (JSON link)
Page Index	`integer`	Optional	A page of incident records. The default page index is 0, indicating the first page. For example, if there exists 50 incidents, and the Page Size (the following parameter) is set to 49, and the Page Index is set to 1 (the second page), only one incident will be displayed. If no value or 0 is provided for both Page Index and Page Size, all incidents will be fetched. If the provide page index is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.
Page Size	`integer`	Optional	The number of incident records to display within a page, ranging from 1 to 1000. If no value or 0 is provided, a default page size of 100 will be applied. If no value or 0 is provided for both Page Index and Page Size, all incidents will be fetched. If the page size is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.
Sort Field	`string`	Optional	The name of the static or dynamic field by which to sort the results. Formatting requirements are as follows: Static fields: Use the field name directly (e.g., `Date Created`). Dynamic fields: Combine the section and field name (e.g., Customer.Name). If the field name contains quotes or spaces, enclose it in quotes and escape any inner quotes (e.g., `Customer "Name".Last "Name"` should be reformatted as `"Customer /"Name/""."Last /"Name/""`). Incident custom fields: Must begin with `Custom` (case-sensitive), such as `Custom Sample`. Sorting is only supported if the field is included in the Static Fields or Dynamic Fields parameter. Nested dynamic fields beyond one level are not supported. Fields containing a period (.) in their name are not supported (except for Incident No.).
Sort Order	`string`	Optional	The order in which the results are sorted. This parameter is used in conjunction with Sort Field to control the sort behaviour.

READER NOTE

Static Fields represents an input parameter as an array of strings. Each field in this array is optional. If you include these fields, the response will contain the specified fields. The fields are:

IR Number, IR Type, Title, Status, Severity, Stage, Priority, Disposition, Tags, Owner, Creator, Timezone, Date Created, Date Modified, Playbook, Description, Conclusion, Investigation Team, Linked Incidents, Incident Raw Data, Event Raw Data

READER NOTE

The fields Incident Raw Data and Event Raw Data can contain large amounts of data. Use these fields cautiously and consider using pagination input parameters (page index and page number) to manage the data volume efficiently.

READER NOTE

For Date/Time parameters Start Time and End Time, all times and timestamps must follow the format: yyyy-mm-dd hh:mm:ss.

e.g. May 15, 2024, 2:32 PM should be written as 2024-05-15 14:32:00.

Body Sample Data

application/json

JSON

{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Filter": [
      [
        {
          "field": "Status",
          "operator": "!=",
          "value": "Open"
        },
        {
          "field": "Severity",
          "operator": "=",
          "value": "High"
        }
      ],
      [
        {
          "section": "Customer",
          "field": "Name",
          "operator": "LIKE",
          "value": "VIP%"
        }
      ]
    ],
    "Static Fields": [
      "IR Number",
      "IR Type",
      "Title",
      "Status",
      "Severity",
      "Stage",
      "Priority",
      "Disposition",
      "Tags",
      "Owner",
      "Creator",
      "Timezone",
      "Date Created",
      "Date Modified",
      "Playbook",
      "Description",
      "Conclusion",
      "Investigation Team",
      "Linked Incidents",
      "Incident Raw Data",
      "Event Raw Data"
    ],
    "Dynamic Fields": {
      "Incident Owner": [
        "Owner Last Update Time",
        "Time Spend"
      ],
      "Customer": [
        "Name",
        "Country"
      ]
    },
    "Start Time": "2019-03-26 00:00:00",
    "End Time": "2021-12-31 10:15:00",
    "Output Format": 2,
    "Page Index": 0,
    "Page Size": 100,
    "Sort Field": "Incident No.",
    "Sort Order": "Ascending"
  }
}

Response

200 OK

application/json

Response Fields

Field Name	Type	Description
error	`string`	The error message if the API request has failed.
keyFields	`JSON Object`	The key fields from the API request.
returnData	`string`	The return data from the API request.
rawData	`JSON Object`	The raw data from the API request.

Sample Data

CODE

{
    "incidents": [
        {
            "Incident No.": "20211222-3",
            "Incident Type": "Playbook - DLP",
            "Title": "*****",
            "Status": "Open",
            "Severity": "Low",
            "Stage": "Data Aggregation Stage",
            "Priority": "1 - Medium",
            "Disposition": "",
            "Tags": "",
            "Owner": "Admin User",
            "Creator": "admin",
            "Closed by": "System User",
            "Time Zone": "PST",
            "Date Created": "2019-04-08 09:17:32",
            "Date Modified": "2019-04-09 11:31:30",
            "Date Closed": "2019-05-14 13:46:00",
            "Playbook": "Endpoint Protection - Unauthorized Access",
            "Description": "",
            "Conclusion": "",
            "Investigation Team": "",
            "Linked Incidents": "20211223-20",
            "Incident Raw Data": "",
            "Customer - Name": "*****",
            "Customer - Country": "France",
            "Incident Owner - Owner Last Update Time": null,
            "Incident Owner - Time Spend": null,
            "Custom Field": "",
            "Events ": [
                {
                    "Id": "*****",
                    "Event Id": 29
                }
            ]
        },
        {
            "Incident No.": "20211222-4",
            "Incident Type": "Playbook - DLP",
            "Title": "",
            "Status": "Open",
            "Severity": "Low",
            "Stage": "Data Aggregation Stage",
            "Priority": "1 - Medium",
            "Disposition": "",
            "Tags": "",
            "Owner": "Admin User",
            "Creator": "admin",
            "Closed by": "System User",
            "Time Zone": "PST",
            "Date Created": "2021-12-22 15:14:26",
            "Date Modified": "2021-12-22 15:51:56",
            "Date Closed": "2021-12-24 16:15:14",
            "Playbook": "Endpoint Protection - Unauthorized Access",
            "Description": "",
            "Conclusion": "",
            "Investigation Team": "",
            "Linked Incidents": "20211225-1,20211225-2",
            "Incident Raw Data": "",
            "Customer - Name": "*****",
            "Customer - Country": "Canada",
            "Incident Owner - Owner Last Update Time": null,
            "Incident Owner - Time Spend": null,
            "Custom Field": "",
            "Events": [
                {
                    "Id": "*****",
                    "Event Id": 29
                },
                {
                    "Id": "*****",
                    "Event Id": 30
                }
            ]
        }
    ]
}

400 BadRequest

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

JSON

{"Error": "The body of the request must be a valid JSON object"}

401 Unauthorized

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

JSON

{"Error": "Invalid authentication key."}

429 TooManyRequests

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

JSON

{"Error": "The request exceeds rate limits or is otherwise blocked by rate limiting policies."}

500 InternalServerError

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

JSON

{"Error": "Unexpected Error."}