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

OPTIONS /v3/caseAttributes

Note

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

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"
}

Additional fields can be included when adding a Case Attribute to a Case, Refer to the following table for a list of available fields for the caseAttributes object:

Field	Description	Required	Type	Example Value(s)
caseId	The ID of the Case associated to the Attribute	TRUE	Integer	1, 2, 3
source	The Attribute’s source	FALSE	String	“Hybrid analysis”
type	The Attribute’s type	TRUE	String	“Detection percentage”
value	The Attribute’s value	TRUE	String	“50”

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.

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

POST /v3/caseAttributes/
{
  "caseId": 1,
  "type": "Detection Percentage",
  "value": "50",
  "source": "Hybrid analysis"
}

JSON Response:

{
  "data": {
      "id": 13,
      "type": "Detection Percentage",
      "value": "50",
      "source": "Hybrid analysis"
  },
  "message": "Created",
  "status": "Success"
}

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"
  }, {
    "id": 2,
    "type": "Phishing Open Rate",
    "value": "20"
  }],
  "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",
    "source": "Hybrid analysis"
  },
  "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 Case Attributes

The basic format for updating a Case Attribute is:

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

Additional fields can be included when updating a Case Attribute to a Case, Refer to the following table for a list of available fields for the caseAttributes object:

Field	Description	Type	Example Value(s)
source	The Attribute’s source	String	“Hybrid analysis”
value	The Attribute’s value	String	“50”

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

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.