Victim Attributes

Attributes are key/value data sets that can be added to a Victim. This type of metadata provides an excellent way to organize, categorize, and integrate Victims into an Organization’s analytic workflow.

Endpoint: /api/v3/victimAttributes

Available Fields

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

OPTIONS /v3/victimAttributes

Hint

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

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

Field Description Type Required for Creation? Updatable?
default A flag indicating whether an Attribute is the default Attribute of its type within the object (this field applies to certain Attribute and data types only) 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
victimId The ID of the Victim associated with the Attribute Integer TRUE FALSE

Note

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

GET /v3/attributeTypes

Create Victim Attributes

The basic format for creating a Victim Attribute is:

POST /v3/victimAttributes
{
    "victimId": 12345,
    "type": "Attribute type goes here",
    "value": "Attribute value goes here"
}

For example, the following query will create an Attribute and add it to the Victim with ID 2:

POST /v3/victimAttributes
{
    "victimId": 2,
    "source": "Phase of Intrusion",
    "type": "Additional Analysis and Context",
    "value": "Based on additional analysis, it was determined that this victim's bank account was hacked."
}

JSON Response

{
    "data": {
        "id": 1,
        "type": "Additional Analysis and Context",
        "value": "Based on additional analysis, it was determined that this victim's bank account was hacked.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "dateAdded": "2021-11-09T15:43:06Z",
        "lastModified": "2021-11-09T15:43:06Z",
        "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 for the victimAttributes object.

Hint

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

Retrieve Victim Attributes

The following section describes how to retrieve Victim Attributes via the /v3/victimAttributes endpoint. In addition to the methods described in this section, you can retrieve Attributes added to a specific Victim by using the following query:

GET /v3/victims/{victimId}?fields=attributes

Retrieve All Victim Attributes

To retrieve all Victim Attributes, use the following query:

GET /v3/victimAttributes

JSON Response

{
    "data": [
        {
            "id": 2,
            "type": "Description",
            "value": "Ransomware attack victim.",
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith"
            },
            "dateAdded": "2021-11-09T15:49:22Z",
            "lastModified": "2021-11-09T15:49:22Z",
            "default": true
        },
        {
            "id": 1,
            "type": "Additional Analysis and Context",
            "value": "Based on additional analysis, it was determined that this victim's bank account was hacked.",
            "source": "Phase of Intrusion",
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "role": "Api User"
            },
            "dateAdded": "2021-11-09T15:43:06Z",
            "lastModified": "2021-11-09T15:43:06Z",
            "default": false
        }
    ],
    "status": "Success"
}

Retrieve a Single Victim Attribute

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

GET /v3/victimAttributes/{victimAttributeId}

For example, the following query will return information about the Victim Attribute with ID 2:

GET /v3/victimAttributes/2

JSON Response

{
    "data": {
        "id": 2,
        "type": "Description",
        "value": "Ransomware attack victim.",
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmith"
        },
        "dateAdded": "2021-11-09T15:49:22Z",
        "lastModified": "2021-11-09T15:49:22Z",
        "default": true
    },
    "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 Victim Attributes

The basic format for updating a Victim Attribute is:

PUT /v3/victimAttributes/{victimAttributeId}
{
    {updatedField}: {updatedValue}
}

For example, the following query will update the value of the Victim Attribute with ID 1 and make it the default Attribute of its type:

PUT /v3/victimAttributes/1
{
    "default": true,
    "value": "Based on additional analysis, it was determined that this victim's social media, bank, and email accounts were hacked as the result of a phishing attack."
}

JSON Response

{
    "data": {
        "id": 1,
        "type": "Additional Analysis and Context",
        "value": "Based on additional analysis, it was determined that this victim's bank account was hacked.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "dateAdded": "2021-11-09T15:43:06Z",
        "lastModified": "2021-11-09T15:43:06Z",
        "default": true
    },
    "message": "Updated",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a PUT request for the victimAttributes object.

Delete Victim Attributes

The basic format for deleting a Victim Attribute is:

DELETE /v3/victimAttributes/{victimAttributeId}

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

DELETE /v3/victimAttributes/1

JSON Response

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

Note

Victim Attributes can be removed from a Victim via the mode field. See Update an Object’s Metadata for more information.