Case Attributes

A Case Attribute is a key/value data set that users can add to a Workflow Case. These Attributes enrich a Case’s data and aid security teams as they investigate a threat and determine the appropriate escalation path for a Case.

Endpoint: /api/v3/caseAttributes

Available Fields

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

OPTIONS /v3/caseAttributes

Hint

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

Alternatively, refer to the following table for a list of available fields that can be included in the body of a POST or PUT request for the caseAttributes object.

Field	Description	Type	Required for Creation?	Updatable?
caseId	The ID of the Case associated to the Attribute	Integer	TRUE	FALSE
default	Indicates whether the Attribute is the default Attribute of its type within the object (this field applies on to certain Attribute and data types)	Boolean	FALSE	TRUE
source	The Attribute’s source	String	FALSE	TRUE
type	The Attribute’s type	String	TRUE	FALSE
value	The Attribute’s value	String	TRUE	TRUE

Note

When setting the type field, you must enter a valid Attribute Type that applies to Cases. To retrieve a list of available Attribute Types, use the following query:

GET /v3/attributeTypes

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.

Create Case Attributes

The basic format for creating a Case Attribute and adding it to a Case is:

POST /v3/caseAttributes
{
    "caseId": 1,
    "type": "Case Attribute Type",
    "value": "Case Attribute Value"
}

For example, the following query will add a Case Attribute to the Case with ID 1.

POST /v3/caseAttributes
{
    "caseId": 1,
    "type": "Phishing Open Rate",
    "value": "30"
}

JSON Response:

{
    "data": {
        "id": 3,
        "type": "Phishing Open Rate",
        "value": "30",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "dateAdded": "2022-04-06T12:40:48Z",
        "lastModified": "2022-04-06T12:40:48Z",
        "default": false
    },
    "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 caseAttributes object.

Hint

Case Attributes can also be created when creating a Case. See the “Create Cases” section of Cases for more information.

Retrieve Case Attributes

Retrieve All Case Attributes

To retrieve all Case Attributes, use the following query:

GET /v3/caseAttributes

JSON Response:

{
    "data": [
        {
            "id": 1,
            "type": "Detection Percentage",
            "value": "50",
            "source": "Hybrid analysis",
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "role": "Api User"
            },
            "dateAdded": "2022-02-15T20:24:04Z",
            "lastModified": "2022-02-15T20:24:16Z",
            "default": false
        },
        {
            "id": 2,
            "type": "Phishing Open Rate",
            "value": "20",
            "createdBy": {
                "id": 1,
                "userName": "jsmith",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "role": "User"
            },
            "dateAdded": "2022-02-15T20:24:18Z",
            "lastModified": "2022-02-15T20:24:37Z",
            "default": false
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Single Case Attribute

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

GET /v3/caseAttributes/{caseAttributeId}

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

GET /v3/notes/1

JSON Response:

{
  "data": {
      "id": 1,
      "type": "Detection Percentage",
      "value": "50",
      "createdBy": {
          "id": 79,
          "userName": "jsmith",
          "firstName": "John",
          "lastName": "Smith",
          "pseudonym": "jsmith"
      },
      "dateAdded": "2022-02-15T20:24:04Z",
      "lastModified": "2022-02-15T20:24:16Z",
      "default": false
  },
  "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 Case Attributes

The basic format for updating a Case Attribute is:

PUT /v3/caseAttributes/{caseAttributeId}
{
    "value": "Case Attribute Value"
}

For example, the following query will update the value of a Case Attribute with ID 1.

POST /v3/caseAttributes/1
{
    "value": "75"
}

JSON Response:

{
    "data": {
        "id": 1,
        "type": "Detection Percentage",
        "value": "75",
        "source": "Hybrid analysis",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "dateAdded": "2022-02-15T20:24:04Z",
        "lastModified": "2022-02-15T20:28:22Z",
        "default": false
    },
    "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 caseAttributes object.

Delete Case Attributes

The basic format to delete a Case Attribute and remove it from a Case is:

DELETE /v3/caseAttributes/{caseAttributeId}

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

DELETE /v3/caseAttributes/1

JSON Response:

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

Delete Case Attributes in Bulk

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