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

Available Fields

You can retrieve a list of available fields for the /v3/cases endpoint, including each field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/cases

Hint

To view all fields, including read-only fields, include the ?show=readonly query parameter.

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 for the cases object.

Field Description Type Required for Creation? Updatable? Example Value(s)
artifacts A list of Artifacts corresponding to the Case Artifact Object FALSE TRUE
{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
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”}}
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”: [{“hostName”:”badguy.com”, “type”: “Host”}]}
attributes A list of Attributes corresponding to the Case Case Attribute Object FALSE TRUE {“data”: [{“type”: “Case Attribute Name”, value”: “Case Attribute Value”, “source”: “Case 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 corresponding to the Case Note Object FALSE TRUE {“data”: [{“text”: “Note about malware case”}]}
resolution The resolution of the Case String FALSE TRUE “Containment Achieved”, “False Positive”
severity The severity of the Case (accepted values include “Low”, “Medium”, “High”, and “Critical”) String TRUE TRUE “Low”, “Medium”, “High”, “Critical”
status The status of the Case (accepted values include “Open” and “Closed”) String TRUE TRUE “Open”, “Closed”
tags A list of Tags corresponding to the Case Tag Object FALSE TRUE {“data”: [{“name”: “Phishing”}]}
tasks A list of Tasks corresponding 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 or edit the Case User Object FALSE TRUE {“data”: [{“userName”: “jsmith@threatconnect.com”}]}
workflowEvents A list of Timeline Events corresponding to the Case Workflow Event Object FALSE TRUE {“data”: [{“summary”: “Case created via API”, “eventDate”: “2021-08-12T12:30:12Z”}]}
workflowTemplate The Workflow Template applied to the Case Workflow Template Object FALSE TRUE
{“name”: “Example Workflow Template”}

{“id”: 12345}

Accepted values for the resolution field include:

  • Containment Achieved
  • Deferred / Delayred
  • Escalated
  • False Positive
  • In Progress / Investigating
  • Not Specified
  • Rejected
  • Restoration Achieved

Attention

Attribute Types for Cases must first be created in the System or Organization in which a Case resides before they can be added to the Case. See the Creating Custom Attribute Types knowledge base article for more information.

Hint

To associate an existing Case or Group to a Case, use the object’s ID when setting the associatedCases or associatedGroups field, respectively (e.g., {"data": [{"id": 12345}]}). To associate an existing Indicator to a Case, use either the Indicator’s ID, or the Indicator’s type and summary (e.g., for a Host Indicator, use its hostName), when setting the associatedIndicators field.

Create Cases

The basic format for creating a Case is:

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

For example, the following query will create a Case named Example Workflow Case that has a severity of Low, has a status of Open, is assigned to jonsmith@threatconnect.com, and includes an Artifact that is associated to an existing Indicator:

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

JSON Response:

{
    "data": {
        "id": 1,
        "xid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
        "name": "Example Workflow Case",
        "dateAdded": "2021-04-09T14:41:27Z",
        "caseOpenTime": "2021-04-09T14:41:27.27Z",
        "caseOpenUser": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "status": "Open",
        "severity": "Low",
        "resolution": "Not Specified",
        "assignee": {
            "type": "User",
            "data": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "johnsmith",
                "role": "User"
            }
        },
        "tasks": {},
        "artifacts": {
            "data": [
                {
                    "id": 12,
                    "summary": "badguy.com",
                    "type": "Host",
                    "intelType": "indicator-Host",
                    "dateAdded": "2021-04-09T14:41:27.27Z",
                    "derivedLink": true,
                    "hashCode": "fTgtpcEQ4JMzFNpXBMhfyXue7s/DchX7uCWedTcqiqA="
                }
            ]
        },
        "notes": {},
        "userAccess": {},
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "owner": "Example Organization",
        "ownerId": 7,
        "attributes": {},
        "associatedGroups": {},
        "associatedIndicators": {},
        "associatedCases": {}
    },
    "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 for the artifacts object.

Note

When creating or updating a Case, you can associate Cases, Indicators, and Groups that do not yet exist in ThreatConnect to the Case. To do so, fill out all required fields for the type of Indicator, type of Group, or Case being associated to the Case. Upon creation of the new Case, any associated objects included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

In addition, you can associate multiple Cases, Indicators, and Groups, as well as apply multiple Tags, to the Case being created in a single POST request.

Retrieve Cases

Retrieve All Cases

To retrieve all Cases, use the following query:

GET /v3/cases

JSON Response:

{
    "data": [
        {
            "id": 1,
            "xid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
            "name": "Example Workflow Case",
            "dateAdded": "2021-04-09T14:41:27.622Z",
            "caseOpenTime": "2021-04-09T14:41:27.622Z",
            "caseOpenUser": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "role": "Api User"
            },
            "status": "Open",
            "severity": "Low",
            "resolution": "Not Specified",
            "assignee": {
                "type": "User",
                "data": {
                    "id": 1,
                    "userName": "[email protected]",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "johnsmith",
                    "role": "User"
                }
            },
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "role": "Api User"
            },
            "owner": "Example Organization",
            "ownerId": 7
        },
        {
            "id": 2,
            "xid": "b2b2b2b2-b2b2-b2b2-b2b2-b2b2b2b2b2b2",
            "name": "Malware Investigation",
            "description": "Case to investigate new malware",
            "dateAdded": "2021-03-25T18:56:22Z",
            "caseOpenTime": "2021-03-25T18:56:22Z",
            "caseOpenUser": {
                "id": 2,
                "userName": "[email protected]",
                "firstName": "Patrick",
                "lastName": "Jones",
                "pseudonym": "patjones",
                "role": "User"
            },
            "status": "Open",
            "severity": "Critical",
            "resolution": "Not Specified",
            "createdBy": {
                "id": 2,
                "userName": "[email protected]",
                "firstName": "Patrick",
                "lastName": "Jones",
                "pseudonym": "patjones",
                "role": "User"
            },
            "owner": "Example Organization",
            "ownerId": 7
        },
        {...}
  ],
  "status": "Success"
}

Retrieve a Single Case

To retrieve a specific Case, use a query in the following format:

GET /v3/cases/{caseId}

For example, the following query will return information about the Case with ID 3:

GET /v3/cases/3

JSON Response:

{
    "data": {
        "id": 3,
        "xid": "c3c3c3c3-c3c3-c3c3-c3c3-c3c3c3c3c3c3",
        "name": "Phishing Investigation",
        "description": "Case to investigate new phishing threat",
        "dateAdded": "2021-04-09T14:41:27.622Z",
        "caseOpenTime": "2021-04-09T14:41:27.622Z",
        "caseOpenUser": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "johnsmith",
            "role": "User"
        },
        "status": "Open",
        "severity": "Medium",
        "resolution": "Not Specified",
        "assignee": {
            "type": "Group",
            "data": {
                "id": 1,
                "name": "SOC Team",
                "description": "Main SOC users",
            }
        },
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "johnsmith",
            "role": "User"
        },
        "owner": "Example Organization",
        "ownerId": 7
    },
    "status": "Success"
}

Request Additional Fields

To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.

Filter Results

To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.

Update Cases

The basic format for updating a Case is:

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

For example, the following query will update the resolution and status of the Case with ID 1. It will also create a new Adversary Group named Extreme Bad Guy that includes an associated Artifact and associate the Group to the Case:

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

JSON Response:

{
    "data": {
        "id": 1,
        "xid": "aa1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
        "name": "Example Workflow Case",
        "dateAdded": "2021-04-09T14:41:27.27Z",
        "caseOpenTime": "2021-04-09T14:41:27Z",
        "caseOpenUser": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "caseCloseTime": "2021-04-12T18:36.18Z",
        "caseCloseUser": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "status": "Closed",
        "severity": "Medium",
        "resolution": "False Positive",
        "tasks": {},
        "artifacts": {
        "data": [
            {
                "id": 12,
                "summary": "badguy.com",
                "type": "Host",
                "intelType": "indicator-Host",
                "dateAdded": "2021-04-09T14:41:27.27Z",
                "derivedLink": true,
                "hashCode": "fTgtpcEQ4JMzFNpXBMhfyXue7s/DchX7uCWedTcqiqA="
            }
        ]},
        "notes": {},
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "owner": "Example Organization",
        "ownerId": 7,
        "attributes": {},
        "associatedGroups": {
            "data": [
                {
                    "id": 17,
                    "ownerName": "Example Organization",
                    "dateAdded": "2021-04-12T18:36.18Z",
                    "webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=17",
                    "type": "Adversary",
                    "name": "Extreme Bad Guy",
                    "createdBy": {
                        "id": 3,
                        "userName": "11112222333344445555",
                        "firstName": "John",
                        "lastName": "Smith",
                        "pseudonym": "jsmithAPI",
                        "role": "Api User"
                    },
                    "lastModified": "2021-04-12T18:36.18Z"
                }
            ]
        },
        "associatedIndicators": {},
        "associatedCases": {}
    },
    "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 for the cases object.

Hint

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

  • associatedCases
  • associatedGroups
  • associatedIndicators
  • tags

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

Warning

Trying to add an Attribute to a Case when the Case Attribute Type’s Max Allowed limit has been reached will result in an error.

Delete Cases

The basic format to delete a Case is:

DELETE /v3/cases/{caseId}

For example, the following query will delete the Case with ID 1:

DELETE /v3/cases/1

JSON Response:

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

Delete Cases in Bulk

To delete Cases in bulk, refer to Delete Case Objects in Bulk.