Add Investigation Details‎‎‎‎ ‎

POST /Command/AddInvestigationDetails

Add details to an incident investigation with HTML rich text. Optionally add IOA or IOC details via JSON format.

Request

Authentication: API keys or JSON web tokens (JWT)

Body Parameters

Parameter Name	Type	Required/Optional	Description
Username	`string`	Required	The username of your D3 SOAR account.
Site	`string`	Required	The D3 SOAR site to run the remote command.
Incident Number	`string`	Required	The incident number to add investigation details to.
Investigation Section	`string`	Required	The section to add the investigation details to.
Investigation Detail Content	`string`	Required	The investigation details in HTML rich text.
Investigation Detail in JSON	`JSON Object`	Optional	Optional JSON field for creating IOA and IOCs. The IOA and IOCs created will be displayed in link analysis.
Editing Type	`string`	Required	Choose whether to add a new investigation detail or overwrite all existing details.

Body Sample Data

application/json

JSON

{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Incident Number": "20221207-11",
    "Investigation Section": "Findings: IOA (Indicator of Attack)",
    "Investigation Detail Content": "This is an IOA.",
    "Investigation Detail in JSON": {
      "Name": "The fake invoice scam",
      "Type": "Phishing email",
      "DetectedUtcTime": "2023-04-12T12:00:00",
      "RelationData": [
        {
          "Type": "Relationship",
          "Direction": "BiDirectional",
          "Label": "Attack",
          "Properties": {
            "property1": "value1",
            "property2": "value2"
          },
          "Start": {
            "Type": "Artifact",
            "Subtype": "Username",
            "Name": "Sample User A",
            "Properties": {
              "property1": "value1",
              "property2": "value2"
            }
          },
          "End": {
            "Type": "Artifact",
            "Subtype": "Username",
            "Name": "Sample User B",
            "Properties": {
              "property1": "value1",
              "property2": "value2"
            }
          }
        },
        {
          "Type": "Relationship",
          "Direction": "Reverse",
          "Label": "Attack",
          "Properties": {
            "property1": "value1",
            "property2": "value2"
          },
          "Start": [
            {
              "Type": "Artifact",
              "Subtype": "Host Name",
              "Name": "Host Name A",
              "Properties": {
                "property1": "value1",
                "property2": "value2"
              }
            }
          ],
          "End": [
            {
              "Type": "Artifact",
              "Subtype": "Host Name",
              "Name": "Host Name B",
              "Properties": {
                "property1": "value1",
                "property2": "value2"
              }
            }
          ]
        }
      ]
    },
    "Editing Type": "Overwrite"
  }
}

Response

200 OK

application/json

Response Fields

Field Name	Type	Description
error	`string`	The error message if the command execution failed.
returnData	`string`	The return data from the API request.
contextData	`array<JSON Object>`	The return data from the API request.

Sample Data

{
    "error": "",
    "returnData": "Successful",
    "contextData": [
    {
        "ID": 30,
        "IncidentId": 25,
        "TypeId": 201,
        "Creator": 1,
        "LastModifiedBy": 1,
        "CreatedUtcTime": "2023-04-11T21:18:47.460",
        "CreatedTime": "2023-04-11T22:18:00",
        "LastModifiedUtcTime": "2023-04-13T22:19:04.513",
        "LastModifiedTime": "2023-04-13T23:19:00",
        "InvestigationDetail": [
            {
                "ID": 112,
                "InvestigationId": 30,
                "AddedBy": 1,
                "LastModifiedBy": 1,
                "RuntimeTaskId": -1,
                "Content": "<p>This is an IOA 22.&nbsp;</p>",
                "Data": "{\n    \"Name\":\"The fake invoice scam\",\n    \"Type\":\"Phishing email\",\n    \"DetectedUtcTime\":\"2023-04-12T12:00:00\",\n    \"RelationData\":[\n        {\n            \"Type\":\"Relationship\",\n            \"Direction\":\"BiDirectional\",\n            \"Label\":\"Attack\",\n            \"Properties\":{\n                \"property1\":\"value1\",\n                \"property2\":\"value2\"\n            },\n            \"Start\":{\n                \"Type\":\"Artifact\",\n                \"Subtype\":\"Username\",\n                \"Name\":\"Sample User A\",\n                \"Properties\":{\n                    \"property1\":\"value1\",\n                    \"property2\":\"value2\"\n                }\n            },\n            \"End\":{\n                \"Type\":\"Artifact\",\n               \"Subtype\":\"Username\",\n                \"Name\":\"Sample User B\",\n                \"Properties\":{\n                    \"property1\":\"value1\",\n                    \"property2\":\"value2\"\n                }\n            }\n        },\n        {\n            \"Type\":\"Relationship\",\n            \"Direction\":\"Reverse\",\n            \"Label\":\"Attack\",\n            \"Properties\":{\n                \"property1\":\"value1\",\n                \"property2\":\"value2\"\n            },\n            \"Start\":[\n                {\n                    \"Type\":\"Artifact\",\n                    \"Subtype\":\"Host Name\",\n                    \"Name\":\"Host Name A\",\n                    \"Properties\":{\n                        \"property1\":\"value1\",\n                        \"property2\":\"value2\"\n                    }\n                }\n            ],\n            \"End\":[\n                {\n                    \"Type\":\"Artifact\",\n                    \"Subtype\":\"Host Name\",\n                    \"Name\":\"Host Name B\",\n                    \"Properties\":{\n                        \"property1\":\"value1\",\n                        \"property2\":\"value2\"\n                    }\n                }\n            ]\n        }\n    ]\n}",
                "Type": 0,
                "CreatedUtcTime": "2023-04-13T22:19:04.513",
                "CreatedTime": "2023-04-13T23:19:00",
                "LastModifiedUtcTime": "2023-04-13T22:19:04.513",
                "LastModifiedTime": "2023-04-13T23:19:00",
                "IsDeleted": false,
                "IndicatorGuid": ""
            }
        ]
    }
  ]
}

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."}