Groups

Groups represent a collection of related behavior and intelligence.

Endpoint: /api/v3/groups

Note

When working with Groups using the ThreatConnect v3 API, you can target a specific Group by its ID or, if one has been assigned to it, XID. While you can use the API to retrieve a Group’s ID, you can also find it in the URL of each Group. If you navigate to the new Details screen, the URL should look like https://app.threatconnect.com/#/details/groups/123456/overview. The number between groups/ and /overview is the Group’s ID. Similarly, if you navigate to the legacy Details screen for a Group, the URL should look like https://app.threatconnect.com/auth/<GROUP-TYPE>/<GROUP-TYPE>.xhtml?<GROUP-TYPE>=123456. The number following <GROUP-TYPE>= is the Group’s ID.

If targeting a Group by its XID, you must use the owner query parameter to specify the owner in which the Group exists.

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/groups endpoint:

OPTIONS /v3/groups

Hint

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

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/groups endpoint for all Group types.

Field	Description	Type	Required for Creation?	Updatable?	Example Value(s)
associatedArtifacts	A list of Artifacts associated to the Group	Artifact Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{ “caseId”: 1, “summary”: “badguy@bad.com”, “type”: “Email Address”}]}
associatedCases	A list of Cases associated to the Group	Case Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“name”: “Hacker Investigation”, “status”: “Open”, “severity”: “Low” }]}
associatedGroups	A list of Groups associated to the Group	Group Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
associatedIndicators	A list of Indicators associated to the Group	Indicator Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“hostName”:”badguy.com”, “type”: “Host”}]}
associatedVictimAssets	A list of Victim Assets associated to the Group	Victim Asset Object	FALSE	TRUE	{“data”: [{“id”: 12345}]} {“data”: [{“phone”: “0123456789”, “type”: “Phone”}]}
attributes [1], [2]	A list of Attributes added to the Group	Group Attribute Object	FALSE	TRUE	{“data”: [{“type”: “Description”, “value”: “A dangerous Group”, “default”: true}]}
externalDateAdded	The date and time when the Group was created externally	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
externalDateExpires	The date and time when the Group expires externally	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
externalLastModified	The date and time when the Group was last modified externally	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
firstSeen	The date and time when the Group was first seen	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
lastSeen	The date and time when the Group was last seen	DateTime	FALSE	TRUE	“2023-10-04T12:34:56Z”
name	The Group’s name	String	TRUE	TRUE	“21-0043847: Threat Actor Capabilities”
ownerId [3]	The ID of the owner to which the Group belongs	Integer	FALSE	FALSE	1, 2, 3,…100
ownerName [3]	The name of the owner to which the Group belongs	String	FALSE	FALSE	“Demo Community”
securityLabels	A list of Security Labels applied to the Group	Security Label Object	FALSE	TRUE	{“data”: [{“name”: “TLP:AMBER”}]}
tags	A list of Tags applied to the Group	Tag Object	FALSE	TRUE	{“data”: [{“name”: “Targeted Attack”}]}
type [4]	The type of Group being created	String	TRUE	FALSE	“Document”, “Email”
xid	The Group’s XID	String	FALSE	FALSE	“a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1”

Group-Specific Fields

Based on the type of Group being created, you may need to include additional fields in the body of a POST request. Similarly, some Group types include additional fields that may be updated via a PUT request.

The following tables lists valid fields that can be included in the body of a POST or PUT request Document, Email, Event, Incident, Report, Signature, and Task Groups.

Document

Field	Description	Type	Required for Creation?	Updatable?
fileName	The file name of the Document	String	FALSE	TRUE
malware [5]	Indicates whether the Document is malware	Boolean	FALSE	TRUE
password	The password associated with the Document	String	FALSE*	TRUE

To upload a file to a Document Group or update the contents of a file uploaded to a Document Group, see the Upload a File to a Document or Report Group and Update a Document or Report Group’s File sections, respectively.

Email

Field	Description	Type	Required for Creation?	Updatable?
body	The Email’s body	String	FALSE	TRUE
from	The Email’s From: field	String	FALSE	TRUE
header	The Email’s header	String	FALSE	TRUE
subject	The Email’s subject	String	FALSE	TRUE

Note

The to field for Email Groups is a read-only field. However, associating an Email Address Victim Asset to an Email Group will populate the Email Group’s to field with that Victim Asset’s email address automatically.

Event

Field	Description	Type	Required for Creation?	Updatable?
eventDate	The date and time when the Event took place	Date	FALSE	TRUE
eventType [6]	The Event’s type	String	FALSE	TRUE
status [7]	The status of the Event	String	FALSE	TRUE

Incident

Field	Description	Type	Required for Creation?	Updatable?
eventDate	The date when the Incident took place	Date	FALSE	TRUE
status [8]	The status of the Incident	String	FALSE	TRUE

Report

Field	Description	Type	Required for Creation?	Updatable?
fileName	The file name of the Report	String	FALSE	TRUE
publishDate	The date and time when the Report was published	Date	FALSE	TRUE
reviews	An Intelligence Review submitted for the Report (see the “Intelligence Reviews” section for more information)	Intelligence Review Object	FALSE	TRUE

To upload a file to a Report Group or update the contents of a file uploaded to a Report Group, see the Upload a File to a Document or Report Group and Update a Document or Report Group’s File sections, respectively.

Signature

Field	Description	Type	Required for Creation?	Updatable?
fileName	The file name of the Signature	String	TRUE	TRUE
fileText [9]	The file text of the Signature	String	TRUE	TRUE
fileType [10]	The file type of the Signature	String	TRUE	TRUE

Note

Accepted values for a Signature Group’s fileType field may also include custom Signature types created by a System Administrator.

Task

Field	Description	Type	Required for Creation?	Updatable?	Example Value(s)
assignments	A list of users assigned to the Task or to whom the Task will be escalated. Valid values for the type of assignment are “Assigned” and “Escalate”	Assignee Object	FALSE	TRUE	{“data”: [{“type”: “Assigned”, “user”: {“id”: 12}}]} {“data”: [{“type”: “Escalate”, “user”: {“id”: 8}}]}
dueDate	The date and time when the Task is due	Date	FALSE	TRUE	“2021-04-30T00:00:00Z”
escalationDate	The date and time when the Task should be escalated	String	FALSE	TRUE	“2021-04-30T00:00:00Z”
reminderDate	The date and time when a reminder about the Task will be sent	String	FALSE	TRUE	“2021-04-30T00:00:00Z”
status [11]	The status of the Task	String	FALSE	FALSE	“In Progress”, “Not Started”

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/groups endpoint:

OPTIONS /v3/groups/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/groups endpoint:

OPTIONS /v3/groups/tql

Create Groups

The following example illustrates the basic format for creating a Group:

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

{
    "name": "Group name goes here",
    "type": "Group type goes here"
    //required fields for the selected Group type go here, if applicable
}

Refer to the Available Fields and Group-Specific Fields sections for a list of available fields that can be included in the body of a POST request to the /v3/groups endpoint.

Note

You can add multiple Attributes, Tags, and Security Labels to a Group in a single POST or PUT request.

Example POST Request

The following request will create an Incident Group for an Incident that took place on Nov. 3, 2021. The Incident will be assigned a status of New, two Tags will be applied to it: the Targeted Attack standard Tag and the T1566 - Phishing ATT&CK® Tag.

Attention

To apply an ATT&CK Tag to a Group, use either the corresponding technique ID or name. For example, to apply the T1566 - Phishing ATT&CK Tag to a Group, either set name to "Phishing" or techniqueId to "T1566" when defining the ATT&CK Tag object in the request body.

Also, if you applied a new Tag to a Group and that Tag matches a synonymous Tag listed in a Tag normalization rule, it will be converted to the main Tag listed in the rule. Similarly, if you applied a new Tag to a Group and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.

Hint

To include the tags field in the API response, append ?fields=tags to the end of the request URL.

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

{
    "type": "Incident",
    "name": "Bad Incident",
    "eventDate": "2021-11-03",
    "status": "New",
    "tags": {
        "data": [
            {
                "name": "Targeted Attack"
            },
            {
                "techniqueId": "T1566"
            }
        ]
    }
}

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com/#/details/groups/3/overview",
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "upVoteCount":"0",
        "downVoteCount":"0",
        "status": "New",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2021-11-03T14:57:4511:04:12Z",
        "legacyLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3"
    },
    "message": "Created",
    "status": "Success"
}

Retrieve Groups

Retrieve All Groups

Send the following request to retrieve data for all Groups:

GET /v3/groups

JSON Response

{
    "data": [
        {
            "id": 10,
            "ownerId": 1,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-10-21T19:54:59Z",
            "webLink": "https://app.threatconnect.com/auth/document/document.xhtml?document=10",
            "type": "Document",
            "name": "Bad Document",
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "owner": "Demo Organization"
            },
            "upVoteCount":"0",
            "downVoteCount":"0",
            "fileName": "indicators.txt",
            "fileSize": 36,
            "status": "Success",
            "documentType": "Text",
            "documentDateAdded": "2021-10-21T19:54:59Z",
            "lastModified": "2022-03-09T12:44:04Z",
            "legacyLink": "https://app.threatconnect.com/auth/document/document.xhtml?document=10"
        },
        {
            "id": 9,
            "ownerId": 1,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-09-17T12:52:49Z",
            "webLink": "https://app.threatconnect.com/auth/email/email.xhtml?email=9",
            "type": "Email",
            "name": "Your Amazon.com order for [email protected]",
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "owner": "Demo Organization"
            },
            "upVoteCount":"0",
            "downVoteCount":"0",
            "to": "[email protected]",
            "from": "[email protected]",
            "subject": "Your Amazon.com order for [email protected]",
            "header": "<email header goes here>",
            "body": "Please visit bad.com to see your order and give us all your money. Muahahahaha!",
            "scoreIncludesBody": true,
            "emailDate": "2021-09-17T12:50:19Z",
            "scoreBreakdown": "Rule SPF Neutral was matched against 'neutral'.\t100\nRule Host was matched against 'bad.com'.\t282\n",
            "lastModified": "2022-03-09T20:39:52Z",
            "legacyLink": "https://app.threatconnect.com/auth/email/email.xhtml?email=9"
        },
        {...}
    ],
    "status": "Success"
}

Hint

Use the owner query parameter to limit the results to a specific owner.

Retrieve a Specific Group

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

Example Request (Group ID)

GET /v3/groups/{groupId}

Example Request (Group XID)

GET /v3/groups/{groupXid}?owner={ownerName}

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

GET /v3/groups/3

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com/#/details/groups/3/overview",
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "upVoteCount":"0",
        "downVoteCount":"0",
        "status": "New",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2021-11-03T14:57:45Z2022-02-16T18:54:23Z",
        "legacyLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3",
    },
    "status": "Success"
}

Update Groups

The following example illustrates the basic format for updating a Group:

Example Request (Group ID)

PUT /v3/groups/{groupId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

Example Request (Group XID)

PUT /v3/groups/{groupXid}?owner={ownerName}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

Refer to the Available Fields and Group-Specific Fields sections for a list of available fields that can be included in the body of a PUT request to the /v3/groups endpoint.

Hint

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

associatedArtifacts
associatedCases
associatedGroups
associatedIndicators
associatedVictimAssets
attributes
securityLabels
tags

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

Example PUT Request

The following request will make the following updates to the Incident Group whose ID is 3:

Associate an Email Address Indicator (verybadguy@bad.com) that exists in Demo Community to the Group
Create a new Host Indicator (ultrabadguy.com) in the API user’s Organization and associate it to the Group
Add a Description (i.e., a default Description Attribute) to the Group
Update the status of the Incident
Remove the Targeted Attack Tag applied to the Group

Hint

To include the associatedIndicators, attributes, and tags fields in the API response, append ?fields=associatedIndicators&fields=attributes&fields=tags to the end of the request URL.

PUT /v3/groups/3
Content-Type: application/json

{
    "associatedIndicators": {
        "data": [
            {
                "address": "[email protected]",
                "type": "EmailAddress",
                "ownerName": "Demo Community"
            },
            {
                "hostName": "ultrabadguy.com",
                "type": "Host"
            }
        ]
    },
    "attributes": {
        "data": [
            {
                "type": "Description",
                "value": "A very severe incident",
                "default": true
            }
        ]
    },
    "status": "Incident Reported",
    "tags": {
        "data": [
            {
                "name": "Targeted Attack"
            }
        ],
        "mode": "delete"
    }
}

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com/#/details/groups/3/overview",
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "upVoteCount":"0",
        "downVoteCount":"0",
        "status": "Incident Reported",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2022-03-09T08:14:23Z",
        "legacyLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3"
    },
    "message": "Updated",
    "status": "Success"
}

Delete Groups

Send a request in the following format to delete a Group:

Example Request (Group ID)

DELETE /v3/groups/{groupId}

Example Request (Group XID)

DELETE /v3/groups/{groupXid}?owner={ownerName}

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

DELETE /v3/groups/1

JSON Response

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

Retrieve, Upload, and Update Files for Document and Report Groups

Retrieve a Document or Report Group’s File

Send a request in the following format to download the contents of the file uploaded to a Document or Report Group:

Example Request (Group ID)

GET /v3/groups/{groupId}/download

Example Request (Group XID)

GET /v3/groups/{groupXid}/download?owner={ownerName}

The contents of the file will be returned as Content-Type: application/octet-stream.

Upload a File to a Document or Report Group

Send a request in the following format to upload the contents of a file to an existing Document or Report Group:

Example Request (Group ID)

POST /v3/groups/{groupId}/upload
Content-Type: application/octet-stream

<raw file contents>

Example Request (Group XID)

POST /v3/groups/{groupXid}/upload?owner={ownerName}
Content-Type: application/octet-stream

<raw file contents>

Hint

When uploading a file to a Group via a POST request, set the updateIfExists query parameter to true to replace any existing file uploaded to the Group. Alternatively, use a PUT request to update the file uploaded to the Group, as described in the `"Update a Document or Report Group's File"<#id27>`_ section.

If uploading a file to the Malware Vault, complete the following steps before performing the upload:

Create a password-protected zip file on your computer that contains the file.
Create a new Document Group with the additional fields malware set to true and password set to the zip file’s password.

Attention

If uploading a file larger than 5GB, contact your System Administrator about increasing the allowed file size for uploads.

Note

If you upload a file whose extension differs from the one specified in the fileName field when the Group was created, use the filename query parameter to update the value of this field so that the extension matches that of the uploaded file.

Filename Considerations

You can upload a file to a Document or Report Group without a filename (i.e., a Document or Report Group whose fileName field has no value). However, creating a Document or Report Group with a filename is recommended.

If a Document or Report Group was created without a filename, you can use the optional filename query parameter to assign the Group a filename. Also, if a Document or Report Group was created with a filename but you are uploading a file with a different file extension, use the filename query parameter to update the Group’s filename so that the extension in it matches that of the uploaded file.

Note

If you upload a file to a Document or Report Group without a filename, the file type will be set to Unrecognized.

Example Request

The following request will upload a file named report.pdf to the Report Group whose ID is 25. In this example, the filename query parameter is included in the request URI because the fileName field was not defined when the Group was created.

Request (HTTP)

POST /v3/groups/25/upload?filename=report.pdf
Content-Type: application/octet-stream

<raw file contents>

Request (cURL)

curl --location --request POST 'https://app.threatconnect.com/api/v3/groups/25/upload?filename=report.pdf' \
--header 'Timestamp: $UNIX_EPOCH_TIMESTAMP' \
--header 'Authorization: TC $ACCESS_ID:$SIGNATURE' \
--header 'Content-Type: application/octet-stream' \
--data '@/Users/jsmith/Desktop/report.pdf'

Response

{
    "message": "Upload successful",
    "status": "Success"
}

Update a Document or Report Group’s File

Send a request in the following format to update the contents of a file uploaded to a Document or Report Group:

Example Request (Group ID)

PUT /v3/groups/{groupId}/upload?filename={fileName.extension}
Content-Type: application/octet-stream

<new file contents>

Example Request (Group XID)

PUT /v3/groups/{groupXid}/upload?filename={fileName.extension}&owner={ownerName}
Content-Type: application/octet-stream

<new file contents>

The following request will update the contents of the file named report.pdf uploaded to the Report Group whose ID is 25:

Request (HTTP)

PUT /v3/groups/25/upload?filename=report.pdf
Content-Type: application/octet-stream

<new file contents>

Request (cURL)

curl --location --request PUT 'https://app.threatconnect.com/api/v3/groups/25/upload?filename=report.pdf' \
--header 'Timestamp: $UNIX_EPOCH_TIMESTAMP' \
--header 'Authorization: TC $ACCESS_ID:$SIGNATURE' \
--header 'Content-Type: application/octet-stream' \
--data '@/Users/jsmith/Desktop/report.pdf'

Response

{
    "message": "Upload successful",
    "status": "Success"
}

Retrieve a PDF Report for a Group

Send a request in the following format to retrieve a PDF report for a Group:

Example Request (Group ID)

GET /v3/groups/{groupId}/pdf

Example Request (Group XID)

GET /v3/groups/{groupXid}/pdf?owner={ownerName}

You can retrieve PDF reports for the following Group types:

Adversary
Attack Pattern
Campaign
Course of Action
Event
Incident
Intrusion Set
Malware
Report
Tactic
Threat
Tool
Vulnerability

Associations

For instructions on creating and managing associations for Groups, see Create and Manage Associations.

Intelligence Reviews

Intelligence Reviews provide members of an organization a way to solicit and provide feedback on a given piece of threat intelligence data in ThreatConnect. Consumers of threat intelligence can use Intelligence Reviews to rate the quality and usefulness of a Group object, identify whether the Group’s intelligence was helpful, and provide narrative comments for the Group. Producers of threat intelligence, on the other hand, can use Intelligence Reviews to collect feedback from stakeholders and determine whether the intelligence they are providing is helpful.

Attention

As of ThreatConnect 7.8, Intelligence Reviews are available for Report Groups only.

Requirements

To create Intelligence Reviews in an Organization, your API user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer.
To create Intelligence Reviews in a Community or Source, your API user account must have a Community role of Contributor, Editor, or Director for that Community or Source.
To update and delete Intelligence Reviews you created in an Organization, your API user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer.
To update and delete Intelligence Reviews you created in a Community or Source, your API user account must have a Community role of Contributor, Editor, or Director for that Community or Source.
To delete Intelligence Reviews any user in an Organization created in the Organization or Communities and Sources the Organization is a member of, your API user account must have an Organization role of Organization Administrator.

Intelligence Review Object Schema

Request Body

The following is the request body schema for an Intelligence Review object that can be used when creating or updating a Group:

reviews: <Object> The Intelligence Review to add to the Group. Note that each user may add only one Intelligence Review per Group.
- data: <Array of Objects> The details of the Intelligence Review.
  
  rating: <Integer> Indicates how valuable you found the Group’s intelligence on a scale of 1 (not valuable) to 5 (very valuable). This field is required if you are creating an Intelligence Review.
  
  reviewHelpful: <Boolean> Specifies whether you found the Group’s intelligence to be helpful (true) or unhelpful (false). This field is required if you are creating an Intelligence Review.
  
  comments: <String> The additional comments provided with the Intelligence Review. (Maximum character length: 500)

Example

"reviews": {
    "data": [
        {
            "rating": 1,
            "reviewHelpful": false,
            "comments": "<string>"
        }
    ]
}

Response Body

The following is the response body schema for an Intelligence Review object that is included in API responses from the /v3/groups endpoint. Note that you must use the fields query parameter in your request and assign it a value of intelReviews to include Intelligence Reviews in API responses:

reviews: <Object> A list of Intelligence Reviews added to the Group.
- data: <Array of Objects> The details of the Intelligence Reviews.
  
  id: <Integer> The Intelligence Review’s ID number.
  
  rating: <Integer> Indicates how valuable the user found the Group’s intelligence on a scale of 1 (not valuable) to 5 (very valuable).
  
  dateAdded: <DateTime> The date and time when the Intelligence Review was created (ISO 8601 format).
  
  lastModified: <DateTime> The date and time when the Intelligence Review was last modified (ISO 8601 format).
  
  createdBy: <Object> The details of the user who submitted the Intelligence Review.
  
  id: <Integer> The user’s ID number.
  
  userName: <String> The user’s username.
  
  firstName: <String> The user’s first name.
  
  lastName: <String> The user’s last name.
  
  pseudonym: <String> The user’s pseudonym.
  
  owner: <String> The Organization to which the user belongs.
  
  comments: <String> The additional comments the user provided with the Intelligence Review. This field is only included for Intelligence Reviews with comments.
  
  editable: <Boolean> Specifies whether you can edit the Intelligence Review.
  
  deletable: <Boolean> Specifies whether you can delete the Intelligence Review.
  
  reviewHelpful: <Boolean> Specifies whether the user found the Group’s intelligence to be helpful (true) or unhelpful (false).

Example

"reviews": {
    "data": [
        {
            "id": 1,
            "rating": 1,
            "dateAdded": "<datetime>",
            "lastModified": "<datetime>",
            "createdBy": {
                "id": 1,
                "userName": "<string>",
                "firstName": "<string>",
                "lastName": "<string>",
                "pseudonym": "<string>",
                "owner": "<string>"
            },
            "comments": "<string>",
            "editable": false,
            "deletable": false,
            "reviewHelpful": false
        }
    ]
}

Create Intelligence Reviews

When creating a Group or updating an existing one, you can add an Intelligence Review to the Group. The following request demonstrates how to add an Intelligence Review to an existing Group. Because Intelligence Review data are not included in the API response by default, the fields query parameter is used and assigned a value of intelReviews to include those data in the response.

Request

PUT /v3/groups/216456?fields=intelReviews
Content-Type: application/json

{
    "reviews": {
        "data": [
            {
                "rating": 5,
                "reviewHelpful": true,
                "comments": "I found the contents of this Report Group to be very helpful and informative during the course of my investigation."
            }
        ]
    }
}

Note

You can add only one Intelligence Review per Group.

Retrieve Intelligence Reviews

When retrieving all Groups or a specific one, you can retrieve Intelligence Reviews by using the fields query parameter and assigning it a value of intelReviews. The following request demonstrates how to include Intelligence Reviews in the API response when retrieving a specific Group.

Request

GET /v3/groups/216456?fields=intelReviews

Update Intelligence Reviews

You can update an Intelligence Review only if its editable field is set to true. The following request demonstrates how to update an Intelligence Review added to an existing Group. Because Intelligence Review data are not included in the API response by default, the fields query parameter is used and assigned a value of intelReviews to include those data in the response.

Request

PUT /v3/groups/216456?fields=intelReviews
Content-Type: application/json

{
    "reviews": {
        "data": [
            {
                "rating": 2,
                "reviewHelpful": false,
                "comments": "On second thought, I did not find this Report Group to be helpful."
            }
        ]
    }
}

Delete Intelligence Reviews

You can delete an Intelligence Review only if its deletable field is set to true. The following request demonstrates how to delete an Intelligence Review added to an existing Group. Because Intelligence Review data are not included in the API response by default, the fields query parameter is used and assigned a value of intelReviews to include those data in the response.

Request

PUT /v3/groups/216456?fields=intelReviews
Content-Type: application/json

{
    "reviews": {
        "data": [
            {
                "id": 1
            }
        ],
        "mode": "delete"
    }
}

MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.