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 the field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/cases

Note

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

Create Cases

The basic format for creating a Case is:

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

Refer to the following table for a list of available fields for the cases object:

Field Description Required Type Example Value(s)
artifacts A list of Artifacts corresponding to the Case FALSE String {“data”: [{“summary”: “badguy@bad.com”, “type”: “Email Address”}]}
assignee The user or group Assignee object for the Case FALSE String {“type”: “User”, “data”: {“userName”: “jonsmith@threatconnect.com”}}
attributes A list of Attributes corresponding to the Case FALSE String {“data”: [{“type”: “Case Attribute Name”, “value”: “Case Attribute Value”, “source”: “Case Attribute Source”}]}
caseCloseTime The date and time a Case was closed FALSE Date “2021-04-30T00:00:00Z”
caseDetectionTime The date and time a security incident or threat was detected (e.g., by a security team) FALSE Date “2021-04-30T00:00:00Z”
caseOccurrence Time The date and time a security incident or threat occurred FALSE Date “2021-04-30T00:00:00Z”
caseOpenTime The date and time a Case was opened FALSE Date “2021-04-30T00:00:00Z”
description A description of the Case FALSE String “New case description”
name The name of the Case TRUE String “New Case”
notes A list of Notes corresponding to the Case FALSE String {“data”: [{“text”: “Note about malware case”}]}
resolution The resolution of the Case FALSE String “Containment Achieved”, “False Positive”
severity The severity of the Case. Valid values are “Low”, “Medium”, “High”, or “Critical” TRUE String “”Low”, “Medium”, “High”, or “Critical”
status The status of the Case TRUE String “Open”, “Closed”
tags A list of Tags corresponding to the Case FALSE String {“data”: [{“name”: “Phishing”}]}
tasks A list of Tasks corresponding to the Case FALSE String {“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 FALSE String {“data”: [{“userName”: “jsmith@threatconnect.com”}]}
workflowEvents A list of Timeline events corresponding to the Case FALSE String {“data”: [{“summary”: “Case created via API”, “eventDate”: “2021-08-12T12:30:12Z”}]}
workflowTemplate The Workflow Template applied to the Case FALSE String {“name”: “Example Workflow Template”}

Note

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.

Available values for the resolution field include:

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

Note

Setting the tags field will replace any existing tag(s) with the one(s) specified.

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

POST /v3/cases/
{
  "assignee": {"type": "User", "data": {"userName": "[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": {
      "count": 0,
    },
    "artifacts": {
      "count": 0,
    },
    "notes": {
      "count": 0,
    },
    "userAccess": {
      "count": 0,
    },
    "createdBy": {
      "id": 3,
      "userName": "11112222333344445555",
      "firstName": "John",
      "lastName": "Smith",
      "pseudonym": "jsmithAPI",
      "role": "Api User"
    },
    "owner": "Example Organization",
    "attributes": {
      "count": 0,
    },
  },
  "message": "Created",
  "status": "Success"
}

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",
      "status": "Open",
      "severity": "Low",
      "resolution": "Not Specified",
      "createdBy": {
          "id": 3,
          "userName": "11112222333344445555",
          "firstName": "John",
          "lastName": "Smith",
          "pseudonym": "jsmithAPI",
          "role": "Api User"
      },
      "owner": "Example Organization",
  },{
      "id": 2,
      "xid": "b2b2b2b2-b2b2-b2b2-b2b2-b2b2b2b2b2b2",
      "name": "Malware Invesigation",
      "description": "Case to investigate new malware",
      "dateAdded": "2021-03-25T18:56:22Z",
      "status": "Open",
      "severity": "Critical",
      "resolution": "Not Specified",
      "createdBy": {
        "id": 2,
        "userName": "[email protected]",
        "firstName": "Patrick",
        "lastName": "Jones",
        "pseudonym": "patjones"
    },
    "owner": "Example Organization"
  }],
  "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",
    "status": "Open",
    "severity": "Medium",
    "resolution": "Not Specified",
    "assignee": {
      "type": "User",
      "data": {
        "id": 1,
        "userName": "[email protected]",
        "firstName": "John",
        "lastName": "Smith",
        "pseudonym": "johnsmith",
        "role": "User"
      }
    },
    "createdBy": {
      "id": 1,
      "userName": "[email protected]",
      "firstName": "John",
      "lastName": "Smith",
      "pseudonym": "johnsmith"
    },
    "owner": "Example Organization"
  },
  "status": "Success"
}

Request Additional Fields

To request additional fields not automatically provided 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}
}

Refer to the following table for a list of available fields that can be updated for the cases object:

Field Description Type Example Value(s)
artifacts A list of Artifacts corresponding to the Case String {“data”: [{“summary”: “badguy@bad.com”, “type”: “Email Address”}]}
assignee The user or group Assignee object for the Case String {“type”: “User”, “data”: {“userName”: “jonsmith@threatconnect.com”}}
attributes A list of Attributes corresponding to the Case String {“data”: [{“type”: “Case Attribute Name”, “value”: “Case Attribute Value”, “source”: ” Case Attribute Source”}]}
caseCloseTime The date and time a Case was closed Date “2021-04-30T00:00:00Z”
caseDetectionTime The date and time a security incident or threat was detected (e.g., by a security team) Date “2021-04-30T00:00:00Z”
caseOccurrenceTime The date and time a security incident or threat occurred Date “2021-04-30T00:00:00Z”
caseOpenTime The date and time a Case was opened Date “2021-04-30T00:00:00Z”
description A description of the Case String “New case description”
name The name of the Case String “New Case”
notes A list of Notes corresponding to the Case String {“data”: [{“text”: “Note about malware case”}]}
resolution The resolution of the Case String “Containment Achieved”, “False Positive”
severity The severity of the Case. Valid values are “Low”, “Medium”, “High”, or “Critical” String “”Low”, “Medium”, “High”, or “Critical”
status The status of the Case String “Open”, “Closed”
tags A list of Tags corresponding to the Case String {“data”: [{“name”: “Phishing”}]}
tasks A list of Tasks corresponding to the Case String {“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 String {“data”: [{“userName”: “jsmith@threatconnect.com”}]}
workflowEvents A list of Timeline events corresponding to the Case String {“data”: [{“summary”: “Case created via API”, “eventDate”: “2021-08-12T12:30:12Z”}]}

Note

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.

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.

Available values for the resolution field include:

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

For example, the following query will update the resolution and status of the Case with ID 1:

PUT /v3/cases/1
{
  "resolution": "False Positive",
  "status": "Closed"
}

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": {
      "count": 0,
    },
    "artifacts": {
      "count": 0,
    },
    "notes": {
      "count": 0,
    },
    "userAccess": {
      "count": 0,
    },
    "createdBy": {
      "id": 3,
      "userName": "11112222333344445555",
      "firstName": "John",
      "lastName": "Smith",
      "pseudonym": "jsmithAPI",
      "role": "Api User"
    },
    "owner": "Example Organization",
    "attributes": {
      "count": 0,
    },
  },
  "message": "Updated",
  "status": "Success"
}

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.