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

Create Cases

The most 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 Required Type Example Value(s)
assignee FALSE String “{“type”: “User”, “data”: {“userName”: “jonsmith@threatconnect.com”}}”
description FALSE String “New case description”
name TRUE String “New Case”
resolution FALSE String “Containment Achieved”, “False Positive”
severity TRUE String “”Low”, “Medium”, “High”, or “Critical”
status TRUE String “Open”, “Closed”

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 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": "jonsmith@threatconnect.com"}}",
  "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:27.622Z",
    "status": "Open",
    "severity": "Low",
    "resolution": "Not Specified",
    "assignee": {
      "type": "User",
      "data": {
        "id": 1,
        "userName": "jonsmith@threatconnect.com",
        "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",
  },
  "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": "pjones+analyst@threatconnect.com",
      "firstName": "Patrick",
      "lastName": "Jones",
      "pseudonym": "patjones"
    },
    "owner": "Example Organization"
  }],
  "count": 2,
  "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": "jsmith@threatconnect.com",
        "firstName": "John",
        "lastName": "Smith",
        "pseudonym": "johnsmith",
        "role": "User"
      }
    },
    "createdBy": {
      "id": 1,
      "userName": "jsmith@threatconnect.com",
      "firstName": "John",
      "lastName": "Smith",
      "pseudonym": "johnsmith"
    },
    "owner": "Example Organization"
  },
  "status": "Success"
}

Request Additional Fields

To request additional fields not automatically provided with each returned Case, refer to the Request Additional Fields for Returned Objects section in this documentation.

Filter Results

To filter returned Cases using ThreatConnect Query Language (TQL), refer to the Filter Results with TQL section in this documentation.

Update Cases

To update a Case, the basic format 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 Type Example Value(s)
assignee String “{“type”: “User”, “data”: {“userName”: “jonsmith@threatconnect.com”}}”
description String “New case description”
name String “New Case”
resolution String “Containment Achieved”, “False Positive”
severity String “”Low”, “Medium”, “High”, or “Critical”
status String “Open”, “Closed”

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.622Z",
    "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",
  },
  "message": "Updated",
  "status": "Success"
}

Delete Cases

The most 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 the Delete Case Objects in Bulk section in this documentation.