Case Attributes

A Case Attribute is a key/value data set that can be added 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 the Case.

Endpoint: /api/v3/caseAttributes

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/caseAttributes endpoint:

OPTIONS /v3/caseAttributes

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

Note

The API response for the OPTIONS /v3/caseAttributes request will include the default, pinned, and securityLabels fields. However, these fields do not apply to Case Attributes and should not be used in POST or PUT requests to the /v3/caseAttributes endpoint.

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 to the /v3/caseAttributes endpoint.

Field	Description	Type	Required for Creation?	Updatable?
caseId	The ID of the Case to which the Attribute is added	Integer	TRUE	FALSE
source	The Attribute’s source	String	FALSE	TRUE
type [1]	The Attribute’s type	String	TRUE	FALSE
value	The Attribute’s value	String	TRUE	TRUE

[1]

Attribute Types for Cases must first be created at the System- or Organization-level before you can add Attributes to a Case, as detailed in the Creating Custom Attribute Types knowledge base article. To retrieve a list of available Attribute Types that apply to Cases, send the following request: GET /v3/attributeTypes?tql=associatedType EQ "Case". Note that you will need to encode the request URL before sending the request.

Attention

If you try to add an Attribute to a Case when the Attribute Type’s Max Allowed limit for Cases has been reached, the API will return a 400 - Bad Request error.

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/caseAttributes endpoint:

OPTIONS /v3/caseAttributes/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/caseAttributes endpoint:

OPTIONS /v3/caseAttributes/tql

Create Case Attributes

The following example illustrates the basic format for creating a Case Attribute:

POST /v3/caseAttributes
Content-Type: application/json

{
    "caseId": 1,
    "type": "Case Attribute Type",
    "value": "Case Attribute Value"
}

For example, the following request will add a Case Attribute to the Case whose ID is 1:

POST /v3/caseAttributes
Content-Type: application/json

{
    "caseId": 1,
    "type": "Phishing Open Rate",
    "value": "30"
}

JSON Response:

{
    "data": {
        "id": 3,
        "dateAdded": "2022-04-06T12:40:48Z",
        "type": "Phishing Open Rate",
        "value": "30",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2022-04-06T12:40:48Z",
        "pinned": false,
        "default": false
    },
    "message": "Created",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a POST request to the /v3/caseAttributes endpoint.

Hint

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

Retrieve Case Attributes

The following section describes how to retrieve Case Attributes via the /v3/caseAttributes endpoint. In addition to the methods described in this section, you can send the following request to retrieve Attributes added to a specific Case: GET /v3/cases/{caseId}?fields=attributes.

Retrieve All Case Attributes

Send the following request to retrieve data for all Case Attributes:

GET /v3/caseAttributes

JSON Response:

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

Retrieve a Specific Case Attribute

Send a request in the following format to retrieve data for a specific Case Attribute:

GET /v3/caseAttributes/{caseAttributeId}

For example, the following request will retrieve data for the Case Attribute whose ID is 3:

GET /v3/caseAttributes/3

JSON Response:

{
    "data": {
        "id": 3,
        "dateAdded": "2022-02-15T20:24:04Z",
        "type": "Summary of Case Findings",
        "value": "After analyzing the threat for which this Case was opened, it was determined that the threat does not pose a risk to Company ABC.",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2022-02-15T21:13:16Z",
        "pinned": false,
        "default": false
    },
    "status": "Success"
}

Update Case Attributes

The following example illustrates the basic format for updating a Case Attribute:

PUT /v3/caseAttributes/{caseAttributeId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

For example, the following query will update the value of the Case Attribute whose ID is 1:

PUT /v3/caseAttributes/1
Content-Type: application/json

{
    "value": "75"
}

JSON Response:

{
    "data": {
        "id": 1,
        "dateAdded": "2022-02-15T20:24:04Z",
        "type": "Detection Percentage",
        "value": "75",
        "source": "Hybrid analysis",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2022-02-15T20:28:22Z",
        "pinned": false,
        "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 to the /v3/caseAttributes endpoint.

Delete Case Attributes

Send a request in the following format to delete a Case Attribute:

DELETE /v3/caseAttributes/{caseAttributeId}

For example, the following request will delete the Case Attribute whose ID is 1:

DELETE /v3/caseAttributes/1

JSON Response:

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

Hint

You can also remove Case Attributes from a Case by using the mode field on the /v3/cases endpoint. See Update an Object’s Metadata for more information.