Cases

A Workflow Case is a single instance of an investigation, inquiry, or other procedure. It contains all required elements of a notable event in a logical structure. Cases can be used to capture key evidence to enable security teams to decide if the Case should be escalated.

Endpoint: /api/v3/cases

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/cases endpoint:

OPTIONS /v3/cases

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

Alternatively, refer to the following tables for a list of available fields that can be included in the body of a POST or PUT request to the /v3/cases endpoint.

Field	Description	Type	Required for Creation?	Updatable?	Example Value(s)
artifacts	A list of Artifacts added to the Case	Artifact Object	FALSE	TRUE	{“data”: [{“summary”: “badguy.com”, “type”: “Host”}]}
assignee	The user or user group assigned to the Case	Assignee Object	FALSE	TRUE	{“type”: “User”, “data”: {“userName”: “jonsmith@threatconnect.com”}} {“type”: “Group”, “data”: {“name”: “SOC Team”}} {“type”: “User”, “data”: {“id”: 3}}
associatedCases	A list of Cases associated to the Case	Case Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“name”: “Hacker Investigation”, “status”: “Open”, “severity”: “Low”}]}
associatedGroups	A list of Groups associated to the Case	Group Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
associatedIndicators	A list of Indicators associated to the Case	Indicator Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“ip”:”66.96.146.129”, “type”: “Address”}]}
attributes [1]	A list of Attributes added to the Case	Case Attribute Object	FALSE	TRUE	{“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”}]}
caseCloseTime	The date and time the Case was closed	Date	FALSE	TRUE	“2021-04-30T00:00:00Z”
caseDetectionTime	The date and time a security incident or threat was detected (e.g., by a security team)	Date	FALSE	TRUE	“2021-04-30T00:00:00Z”
caseOccurrenceTime	The date and time a security incident or threat occurred	Date	FALSE	TRUE	“2021-04-30T00:00:00Z”
caseOpenTime	The date and time the Case was opened	Date	FALSE	TRUE	“2021-04-30T00:00:00Z”
description	A description of the Case	String	FALSE	TRUE	“This Case is an investigation of a high-level hacker incident that occurred on critical systems.”
name	The name of the Case	String	TRUE	TRUE	“Hacker Investigation”
notes	A list of Notes added to the Case	Note Object	FALSE	TRUE	{“data”: [{“text”: “Upload all relevant research performed for this Case to the SOC Team shared drive.”}]}
resolution [2]	The resolution of the Case	String	FALSE	TRUE	“Containment Achieved”, “False Positive”
severity [3]	The severity of the Case (accepted values include “Low”, “Medium”, “High”, and “Critical”)	String	TRUE	TRUE	“Low”, “Medium”, “High”, “Critical”
status [4]	The status of the Case (accepted values include “Open” and “Closed”)	String	TRUE	TRUE	“Open”, “Closed”
tags	A list of Tags applied to the Case	Tag Object	FALSE	TRUE	{“data”: [{“name”: “Phishing”}]}
tasks	A list of Tasks added to the Case	Task Object	FALSE	TRUE	{“data”: [{“name”: “Investigate Phishing Email”, “workflowPhase”: 1, “workflowStep”: 1}]}
userAccess	A list of users that, when defined, are the only ones allowed to view and edit the Case	User Object	FALSE	TRUE	{“data”: [{“userName”: “jsmith@threatconnect.com”}]} {“data”: [{“id”: 3}]}
workflowEvents	A list of Timeline Events for the Case	Workflow Event Object	FALSE	TRUE	{“data”: [{“summary”: “Case created via API”, “eventDate”: “2021-08-12T12:30:12Z”}]}
workflowTemplate	The Workflow applied to the Case	Workflow Template Object	FALSE	TRUE	{“name”: “Phishing Email Analysis”} {“id”: 12345}

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/cases endpoint:

OPTIONS /v3/cases/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/cases endpoint:

OPTIONS /v3/cases/tql

Create Cases

The following example illustrates the basic format for creating a Case:

POST /v3/cases
{
    "name": "Case name",
    "status": "Case status",
    "severity": "Case severity"
}

For example, the following request will create a Case named “Phishing Investigation.” It will also complete the following actions for the Case:

Set the Case’s severity to Low
Set the Case’s status to Open
Assign the Case to smithj@threatconnect.com
Create an Artifact within the Case and associate the Artifact to the existing Indicator whose ID is 2
Apply the T1566 - Phishing ATT&CK® Tag to the Case

Attention

When applying ATT&CK Tags to a Case, do not include the corresponding technique/sub-technique ID in the Tag’s name. For example, to apply the T1566 - Phishing ATT&CK Tag to a Case, use Phishing as the Tag name.

Also, if you applied a new Tag to a Case and that Tag matches a synonymous Tag listed in a Tag normalization rule, it will be converted to the main Tag listed in the rule. Similarly, if you applied a new Tag to a Case and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.

Hint

To include the artifacts and tags fields in the API response, append ?fields=artifacts&fields=tags to the end of the request URL.

POST /v3/cases
{
    "artifacts": {
        "data": [
            {
                "summary": "badguy.com",
                "type": "Host",
                "associatedIndicators": {
                    "data": [
                        {
                            "id": "2"
                        }
                    ]
                }
            }
        ]
    },
    "assignee": {
        "type": "User",
        "data": {
            "userName": "[email protected]"
        }
    },
    "name": "Phishing Investigation",
    "severity": "Low",
    "status": "Open",
    "tags": {
        "data": [
            {
                "name": "Phishing"
            }
        ]
    }
}

JSON Response:

{
    "data": {
        "id": 1,
        "xid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
        "name": "Phishing Investigation",
        "dateAdded": "2023-03-09T14:41:27Z",
        "lastUpdated": "2023-03-09T14:41:27Z",
        "caseOpenTime": "2023-03-09T14:41:27.27Z",
        "caseOpenUser": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "status": "Open",
        "severity": "Low",
        "resolution": "Not Specified",
        "assignee": {
            "type": "User",
            "data": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "JMS",
                "owner": "Demo Organization"
            }
        },
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "owner": "Demo Organization",
        "ownerId": 1
    },
    "message": "Created",
    "status": "Success"
}

Refer to the Available Fields and section for a list of available fields that can be included in the body of a POST request to the /v3/cases endpoint.

Retrieve Cases

Retrieve All Cases

Send the following request to retrieve data for all Cases:

GET /v3/cases

JSON Response:

{
    "data": [
        {
            "id": 1,
            "xid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
            "name": "Phishing Investigation",
            "dateAdded": "2023-03-09T14:41:27.622Z",
            "lastUpdated": "2023-03-09T14:41:27.622Z",
            "caseOpenTime": "2023-03-09T14:41:27.622Z",
            "caseOpenUser": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "owner": "Demo Organization"
            },
            "status": "Open",
            "severity": "Low",
            "resolution": "Not Specified",
            "assignee": {
                "type": "User",
                "data": {
                    "id": 1,
                    "userName": "[email protected]",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "JMS",
                    "owner": "Demo Organization"
                }
            },
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "owner": "Demo Organization"
            },
            "owner": "Demo Organization",
            "ownerId": 1
        },
        {
            "id": 2,
            "xid": "b2b2b2b2-b2b2-b2b2-b2b2-b2b2b2b2b2b2",
            "name": "Malware Investigation",
            "description": "Case to investigate new malware",
            "dateAdded": "2023-03-17T18:56:22Z",
            "lastUpdated": "2023-03-25T11:25:34Z",
            "caseOpenTime": "2023-03-17T18:56:22Z",
            "caseOpenUser": {
                "id": 2,
                "userName": "[email protected]",
                "firstName": "Pat",
                "lastName": "Jones",
                "pseudonym": "patjones",
                "owner": "Demo Organization"
            },
            "status": "Open",
            "severity": "Critical",
            "resolution": "Not Specified",
            "createdBy": {
                "id": 2,
                "userName": "[email protected]",
                "firstName": "Pat",
                "lastName": "Jones",
                "pseudonym": "patjones",
                "owner": "Demo Organization"
            },
            "owner": "Demo Organization",
            "ownerId": 1
        },
        {...}
    ],
    "status": "Success"
}

Attention

Only Cases to which your API user account has viewing access will be included in the API response.

Retrieve a Specific Case

Send a request in the following format to retrieve data for a specific Case:

GET /v3/cases/{caseId}

For example, the following request will retrieve data for the Case whose ID is 3:

GET /v3/cases/3

JSON Response:

{
    "data": {
        "id": 3,
        "xid": "c3c3c3c3-c3c3-c3c3-c3c3-c3c3c3c3c3c3",
        "name": "Analyze Suspicious Email and Report Findings",
        "dateAdded": "2023-03-19T14:41:27.622Z",
        "lastUpdated": "2023-03-21T09:22:39.622Z",
        "caseOpenTime": "2023-03-09T14:41:27.622Z",
        "caseOpenUser": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "JMS",
            "owner": "Demo Organization"
        },
        "status": "Open",
        "severity": "Medium",
        "resolution": "Not Specified",
        "assignee": {
            "type": "Group",
            "data": {
                "id": 1,
                "name": "SOC Team",
                "description": "Members of the SOC team.",
            }
        },
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "JMS",
            "owner": "Demo Organization"
        },
        "owner": "Demo Organization",
        "ownerId": 1
    },
    "status": "Success"
}

Update Cases

The following example illustrates the basic format for updating a Case:

PUT /v3/cases/{caseId}
{
    {updatedField}: {updatedValue}
}

For example, the following request will make the following updates to the Case whose ID is 1:

Set the Case’s resolution to False Positive
Set the Case’s status to Closed
Create a new Adversary Group named Extreme Bad Guy that is associated to the Artifact whose ID is 4, and then associate the Group to the Case

Hint

To include the associatedGroups field in the API response, append ?fields=associatedGroups to the end of the request URL.

PUT /v3/cases/1
{
    "resolution": "False Positive",
    "status": "Closed",
    "associatedGroups": {
        "data": [
            {
                "name": "Extreme Bad Guy",
                "type": "Adversary",
                "associatedArtifacts": {
                    "data": [
                        {
                            "id": 4
                        }
                    ]
                }
            }
        ]
    }
}

JSON Response:

{
    "data": {
        "id": 1,
        "xid": "aa1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
        "name": "Phishing Investigation",
        "dateAdded": "2023-03-09T14:41:27.27Z",
        "lastUpdated": "2023-03-30T13:27:41Z",
        "caseOpenTime": "2023-03-09T14:41:27Z",
        "caseOpenUser": {
            "id": 3,
            "userName": "11112222333344445555"
        },
        "caseCloseTime": "2021-04-12T18:36.18Z",
        "caseCloseUser": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "status": "Closed",
        "severity": "Low",
        "resolution": "False Positive",
        "assignee": {
            "type": "User",
            "data": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "JMS",
                "owner": "Demo Organization"
            }
        },
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "owner": "Demo Organization",
        "ownerId": 1
    },
    "message": "Updated",
    "status": "Success"
}

Refer to the Available Fields and section for a list of available fields that can be included in the body of a PUT request to the /v3/cases endpoint.

Hint

When updating a Case, you can use the mode field to add or remove the following metadata:

associatedCases
associatedGroups
associatedIndicators
attributes
tags

See Update an Object’s Metadata for instructions on using the mode field.

Attention

If you try to add an Attribute to a Case when the Attribute Type’s Max Allowed limit for Cases has been reached, the API will return a 400 Bad Request error.

Delete Cases

Send a request in the following format to delete a Case:

DELETE /v3/cases/{caseId}

For example, the following request will delete the Case whose ID is 1:

DELETE /v3/cases/1

JSON Response:

{
    "message": "Deleted",
    "status": "Success"
}

Delete Cases in Bulk

For instructions on deleting Cases in bulk, refer to Delete Case Objects in Bulk.

Associations

For instructions on creating and managing associations for Cases, see Create and Manage Associations.

MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.