Victims

Victims are used to describe a specific organization or group that has been targeted or whose Assets have been exploited.

Endpoint: /api/v3/victims

Available Fields

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

OPTIONS /v3/victims

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 victims object.

Field Description Type Required for Creation? Updatable? Example Value(s)
assets A list of Victim Assets corresponding to the Victim Victim Asset Object FALSE TRUE
{“data”: [{“id”: 12345}]}

{“data”: [{“phone”: “0123456789”, “type”: “Phone”}]}
associatedGroups A list of Groups associated to the Victim Group Object FALSE TRUE
{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
attributes A list of Attributes corresponding to the Victim Victim Attribute Object FALSE TRUE {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”]}}
name The Victim’s name String TRUE TRUE “Bob Loblaw”
nationality The Victim’s nationality String FALSE TRUE “American”
org The Victim’s organization String FALSE TRUE “Company ABC”
securityLabels A list of Security Labels applied to the Victim Security Label Object FALSE TRUE {“data”: [{“name”: “TLP:AMBER”}]}
suborg The Victim’s suborganization String FALSE TRUE “HR Department”
tags A list of Tags applied to the Victim Tag Object FALSE TRUE {“data”: [{“name”: “Targeted Attack”}]}
workLocation The Victim’s work location String FALSE TRUE “Washington, D.C.”

The following Victim Asset types can be added to a Victim via the assets field:

  • EmailAddress
  • NetworkAccount
  • Phone
  • SocialNetwork
  • WebSite

Note

A list of available Attribute Types can be retrieved with the following query:

GET /v3/attributeTypes

Hint

To associate an existing Group to a Victim, use the Group’s ID when setting the associatedGroups field (e.g., {"data": [{"id": 12345}]}).

Create Victims

The basic format for creating a Victim is:

POST /v3/victims
{
    "name": "John Doe"
}

For example, the following query will create a Victim. Note that all optional fields available for the victims object are included in this request.

POST /v3/victims
{
    "name": "John Doe",
    "assets": {"data": [{"address": "[email protected]", "addressType": "Corporate email", "type": "EmailAddress"}]},
    "associatedGroups": {"data": [{"id": 12345}], [{"name": "Bad Adversary", "type": "Adversary"}]},
    "attributes": {"data": [{"type": "Additional Analysis and Context", "value": "Example value", "source": "Example Source"}]},
    "nationality": "American",
    "org": "Company ABC",
    "securityLabels": {"data": [{"name": "TLP:AMBER"}]},
    "suborg": "HR Department",
    "tags": {"data": [{"name": "Targeted Attack"}]},
    "workLocation": "Washington, D.C."
}

JSON Response

{
    "data": {
        "id": 2,
        "ownerName": "Demo Organization",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=2",
        "tags": {
            "data": [{
                "id": 11,
                "name": "Targeted Attack",
                "lastUsed": "2021-11-05T19:16:52Z"
            }]
        },
        "securityLabels": {
            "data": [{
                "id": 3,
                "name": "TLP:AMBER",
                "description": "This security label is used for information that requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
                "color": "FFC000",
                "owner": "System",
                "dateAdded": "2016-08-31T00:00:00Z"
            }]
        },
        "name": "John Doe",
        "org": "Company ABC",
        "suborg": "HR Department",
        "workLocation": "Washington, D.C.",
        "nationality": "American",
        "assets": {
            "data": [{
                "id": 2,
                "type": "EmailAddress",
                "victimId": 2,
                "address": "[email protected]",
                "addressType": "Corporate email"
            }]
        },
        "attributes": {
            "data": [{
                "id": 1,
                "type": "Additional Analysis and Context",
                "value": "Example value",
                "source": "Example Source",
                "createdBy": {
                    "id": 3,
                    "userName": "11112222333344445555",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "jsmithAPI",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-05T19:16:52Z",
                "lastModified": "2021-11-05T19:16:52Z",
                "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 victims object.

Note

You can add multiple Attributes, Tags, and Security Labels to the Victim being created in a single POST request. Similarly, you can associate multiple Groups to the Victim being created in a single POST request.

Note

When creating a Victim, you can apply Tags that do not yet exist in ThreatConnect to it. To do so, fill out all required fields for each new Tag. Upon creation of the new Victim, any Tags included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Similarly, you can associate Groups that do not yet exist in ThreatConnect to the Victim. To do so, fill out all required fields for the type of Group being associated to the Victim. Upon creation of the new Victim, any associated Groups included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Retrieve Victims

Retrieve All Victims

To retrieve all Victims, use the following query:

GET /v3/victims

JSON Response

{
    "data": [
        {
            "id": 1,
            "ownerName": "Demo Organization",
            "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=1",
            "name": "Bob Loblaw"
        },
        {
            "id": 2,
            "ownerName": "Demo Organization",
            "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=2",
            "name": "John Doe",
            "org": "Company ABC",
            "suborg": "HR Department",
            "workLocation": "Washington, D.C.",
            "nationality": "American"
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Single Victim

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

GET /v3/victims/{victimId}

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

GET /v3/victims/3

JSON Response

{
    "data": {
        "id": 3,
        "ownerName": "Demo Organization",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=3",
        "name": "Bill Smith",
        "org": "Company XYZ",
        "suborg": "Finance Department",
        "workLocation": "Pittsburgh, Pennsylvania",
        "nationality": "American"
    },
    "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 Victims

The basic format for updating a Victim is:

PUT /v3/victims/{victimId}
{
    {updatedField}: {updatedValue}
}

For example, the following query will complete the following actions for a Victim with ID 2:

  • Add a WebSite Victim Asset to the Victim;
  • Update the Victim’s name;
  • Replace the TLP: AMBER Security Label applied to the Victim with a TLP: RED Security Label.
PUT /v3/victims/2
{
    "assets": {"data": [{"website": "evilll.com", "type": "WebSite"}]},
    "name": "Jane Doe",
    "securityLabels": {"data": [{"name": "TLP:RED"}], "mode": "replace"}
}

JSON Response

{
    "data": {
        "id": 2,
        "ownerName": "Demo Organization",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=2",
        "tags": {
            "data": [{
                "id": 11,
                "name": "Targeted Attack",
                "lastUsed": "2021-11-05T19:16:52Z"
            }]
        },
        "securityLabels": {
            "data": [{
                "id": 4,
                "name": "TLP:RED",
                "description": "This security label is used for information that cannot be effectively acted upon by additional parties, and could lead to impacts on a party"s privacy, reputation, or operations if misused.",
                "color": "FF0033",
                "owner": "System",
                "dateAdded": "2016-08-31T00:00:00Z"
            }]
        },
        "name": "Jane Doe",
        "org": "Company ABC",
        "suborg": "HR Department",
        "workLocation": "Washington, D.C.",
        "nationality": "American",
        "assets": {
            "data": [{
                "id": 3,
                "type": "WebSite",
                "victimId": 2,
                "website": "evilll.com"
            }, {
                "id": 2,
                "type": "EmailAddress",
                "victimId": 2,
                "address": "[email protected]"
            }]
        },
        "attributes": {
            "data": [{
                "id": 1,
                "type": "Additional Analysis and Context",
                "value": "Example value",
                "source": "Example Source",
                "createdBy": {
                    "id": 3,
                    "userName": "11112222333344445555",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "jsmithAPI",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-05T19:16:52Z",
                "lastModified": "2021-11-05T19:16:52Z",
                "default": false
            }]
        }
    },
    "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 victims object.

Hint

When updating a Victim, you can use the mode field to add or remove the following metadata:

  • associatedGroups
  • attributes
  • securityLabels
  • tags

See Update an Object’s Metadata for instructions on using the mode field.

Delete Victims

The basic format for deleting a Victim is:

DELETE /v3/victims/{victimId}

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

DELETE /v3/victims/1

JSON Response

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