Include Additional Fields for Returned Objects¶
When retrieving objects, you can request additional fields not automatically included with each returned object by including the ?fields= query parameter, followed by the field name(s) you want to include, in your query. To view a list of available options to set in the ?fields= query parameter for an object, use the following query:
OPTIONS /v3/{objectName}/fields
Example Request¶
The following query will return information about the Indicator with ID 12345, including Tags applied to the Indicator, ThreatAssess information for the Indicator, and Groups associated to the Indicator:
GET /v3/indicators/12345?fields=tags&fields=threatAssess&fields=associatedGroups
JSON Response:
{
"data": {
"id": 12345,
"ownerName": "Demo Organization",
"dateAdded": "2021-10-26T13:05:02Z",
"webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=veryultrabadguy.com",
"tags": {
"data": [
{
"id": 11,
"name": "Targeted Attack",
"lastUsed": "2021-11-03T15:04:49Z"
}
]
},
"type": "Host",
"lastModified": "2021-10-26T15:16:43Z",
"rating": 4.00,
"confidence": 70,
"threatAssessRating": 1.89,
"threatAssessConfidence": 45.41,
"threatAssessScore": 673,
"summary": "badguy.com",
"privateFlag": false,
"active": true,
"activeLocked": false,
"associatedGroups": {
"data": [
{
"id": 94271,
"type": "Incident",
"ownerName": "Demo Organization",
"dateAdded": "2021-11-03T15:04:49Z",
"webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=94271",
"name": "Bad Incident",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization",
"systemRole": "Api User"
},
"status": "Incident Reported",
"eventDate": "2021-11-03T00:00:00Z"
}
]
},
"hostName": "badguy.com",
"dnsActive": false,
"whoisActive": false
},
"status": "Success"
}
Additional association levels for intelligence items may also be retrieved. For example, adding .attributes to the ?fields=associatedGroups query parameter in the preceding query will also return Attributes added to the Group associated to the Indicator:
GET /v3/indicators/12345?fields=tags&fields=threatAssess&fields=associatedGroups.attributes
JSON Response:
{
"data": {
"id": 12345,
"ownerName": "Demo Organization",
"dateAdded": "2021-10-26T13:05:02Z",
"webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=veryultrabadguy.com",
"tags": {
"data": [
{
"id": 11,
"name": "Targeted Attack",
"lastUsed": "2021-11-03T15:04:49Z"
}
]
},
"type": "Host",
"lastModified": "2021-10-26T15:16:43Z",
"rating": 4.00,
"confidence": 70,
"threatAssessRating": 1.89,
"threatAssessConfidence": 45.41,
"threatAssessScore": 673,
"summary": "badguy.com",
"privateFlag": false,
"active": true,
"activeLocked": false,
"associatedGroups": {
"data": [
{
"id": 94271,
"type": "Incident",
"ownerName": "Demo Organization",
"dateAdded": "2021-11-03T15:04:49Z",
"webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=94271",
"name": "Bad Incident",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization",
"systemRole": "Api User"
},
"attributes": {
"data": [
{
"id": 1077825,
"type": "Additional Analysis and Context",
"value": "Based on internal analysis, this incident was bad.",
"source": "Phase of Intrusion",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization",
"systemRole": "Api User"
},
"dateAdded": "2021-11-04T19:07:01Z",
"lastModified": "2021-11-04T19:07:01Z",
"default": false
}
]
},
"status": "Incident Reported",
"eventDate": "2021-11-03T00:00:00Z"
}
]
},
"hostName": "badguy.com",
"dnsActive": false,
"whoisActive": false
},
"status": "Success"
}
Attention
By default, you can only retrieve one association level for threat intelligence items at a time. To retrieve more than one association level at a time, contact your System Administrator and have them do one of the following:
- Enable the Allow User to Exceed API Link Limit setting on your API user account. Instructions for enabling this setting are available in the Creating User Accounts knowledge base article.
- Update the v3ApiIntelLinkLimit system setting to allow for more than one association level to be retrieved at a time.
Note
The ?tql= and ?fields= query parameters can be combined in a single request. For example, the following query will return all Indicators, along with their respective Tags and Attributes, that belong to the Demo Community owner:
GET /v3/indicators?tql=ownerName EQ "Demo Community"&fields=tags&fields=attributes
Depending on the tool you’re using to interact with the ThreatConnect API, it may be necessary to manually encode the URL in your request when including query parameters. For example, some tools may accept ?tql=ownerName EQ "Demo Community"&fields=tags&fields=attributes as a valid URL and automatically encode it, while others may require you to manually encode the URL (e.g., ?tql=ownerName%20EQ%20%22Demo%20Community%22&fields=tags&fields=attributes). If you submit a request with query parameters and a 401 Unauthorized error is returned, verify whether the URL in your request is encoded properly for your preferred API tool.