Submitting New Data

You may submit data to the graph via an HTTP POST request the following URL:

  • https://graph.facebook.com/v4.0/threat_descriptors

NOTE: The call to /threat_indicators is deprecated as of v2.4 of the ThreatExchange API. If you attempt to access this endpoint in v2.4+, it will create a threat descriptor and the associated threat indicator behind the scenes.

Parameters

The following submission parameters are available for API use (bold parameters are required). Column names for bulk upload/download in the UI (click here for more information) are also indicated.

API NameUI Display NameUI CSV NameDescription
access_token

Not used for the UI

Not used for the UI

The key for authenticating to the API, in the format

your-app-id|your-app-secret

. For example, if our app ID was 555 and our app secret aSdF123GhK, our access_token would be "555|aSdF123GhK".

descriptionDescriptiontd_description

A short summary of the indicator and threat.

indicatorRaw indicatortd_raw_indicator

The indicator data being submitted.

typeIndicator typetd_indicator_type

The kind of indicator being described, see

IndicatorType

for the list of allowed values.

privacy_typeVisibilitytd_visibility

The kind of privacy for the indicator. See

PrivacyType

for the list of allowed values.

privacy_membersWhitelist apps

,

Privacy groups
td_whitelist_apps

,

td_privacy_groups

A comma-delimited list of

ThreatExchangeMembers

allowed to see the indicator, and only applies when

privacy_type

is set to

HAS_WHITELIST

or

HAS_PRIVACY_GROUP

.

share_levelShare leveltd_share_level

A designation of how the indicator may be shared based on the

US-CERT's Traffic Light Protocol

. See

ShareLevelType

for the list of allowed values. Note: GREEN/WHITE requires VISIBLE, and AMBER/RED requires HAS_WHITELIST or HAS_PRIVACY_GROUP.

statusStatustd_status

Indicates if the indicator is labeled as malicious. See

StatusType

for the list of allowed values.

tagsSubjective tagstd_subjective_tags

A comma-separated list of tags you want to publish. (This will replace any existing tags.) Tags are not strictly required but do note that they are essential for your collaborators to discover data you contribute.

add_tags

Not used for the UI.

Not used for bulk upload/download in the UI.

To add tags to an object without overwriting existing tags.

remove_tags

Not used for the UI.

Not used for bulk upload/download in the UI.

Remove tags asocciated with an object.

confidenceConfidencetd_confidence

A score for how likely the indicator's

status

is accurate, ranging from 0 to 100.

expired_onExpire timetd_expire_time

Time the indicator is no longer considered a threat, in ISO 8601 date format.

first_activeFirst activetd_first_active

Time when the opinion first became valid.

last_activeLast activetd_last_active

Time when the opinion stopped being valid.

review_statusReview statustd_review_status

Describes how the indicator was vetted. See

ReviewStatusType

for the list of allowed values.

severitySeveritytd_severity

A rating of how severe the indicator is when found in an incident. See

SeverityType

for the list of allowed values.

Example submission of a malicious domain using the UI:

Example bulk upload from CSV/JSON using the UI: click here.

Example submission of a malicious domain using the API:

https://graph.facebook.com/v4.0/threat_descriptors?access_token=555|aSdF123GhK

POST DATA:
indicator=evil-domain.biz
&type=DOMAIN
&tags=testingtags
&status=MALICIOUS
&description=This%20domain%20was%20hosting%20malware
&privacy_type=VISIBLE

Data returned:

{
"id": "853037291373757",
"success": true
}