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}

[1]

Attribute Types for Cases must first be created at the System- or Organization-level before you can add Attributes to a Case, as detailed in the Creating Custom Attribute Types knowledge base article. To retrieve a list of available Attribute Types and determine whether an Attribute Type applies to Cases, send the following request and then review the attributeTypeMappings field included in the response: GET /v3/attributeTypes?fields=mapping.

[2]	The following are accepted values for the resolution field: Containment Achieved Deferred / Delayed Escalated False Positive In Progress / Investigating Not Specified Rejected Restoration Achieved

[3]	The following are accepted values for the severity field: Low Medium High Critical

[4]	The following are accepted values for the status field: Open Closed

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.

Create Associations

You can create associations between Cases in your Organization and Groups, Indicators, and other Cases in your Organization. If cross-owner associations are enabled on your ThreatConnect instance, you can also create associations between Groups and Indicators in Communities and Sources to which you have access and Cases in your Organization.

When creating associations for Cases using the ThreatConnect v3 API, follow these guidelines:

• To create an association to a new Case, include all fields required to create a Case when setting the associatedCases field.
• To create an association to an existing Case, use the Case’s ID when setting the associatedCases field (e.g., "associatedCases": {"data": [{"id": 12345}]}).
• To create an association to a new Group, include all fields required to create the type of Group when setting the associatedGroups field. To create the Group in a Community or Source, include the ownerId or ownerName field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Group when setting the associatedGroups field.
• To create an association to an existing Group, use the Group’s ID when setting the associatedGroups field.
• To create an association to a new Indicator, include all fields required to create the type of Indicator when setting the associatedIndicators field. To create the Indicator in a Community or Source, include the ownerId or ownerName field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Indicator when setting the associatedIndicators field.
• To create an association to an existing Indicator, use the Indicator’s ID, or use its summary and type (e.g., "associatedIndicators": {"data": [{"type": "Host", "hostname": "badguy.com"}]}), when setting the associatedIndicators field. To create an association to an Indicator in a Community or Source using the Indicator’s summary and type, include the ownerId or ownerName field and specify the ID or name, respectively, of the Community or Source to which the Indicator belongs when setting the associatedIndicators field.

Note

You can associate multiple Cases, Indicators, and Groups to a Case in a single POST or PUT request.

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.

---

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