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.