Getting Started with ThreatExchange

Create a Facebook App

Before using the ThreatExchange API, you'll need to create a Facebook app. To get started, you need to do the following:

  1. Log in to Facebook using the account you'll use to create the app. This must be a real Facebook account.
  2. Go to the App Dashboard and create a new app.
  3. Take the app out of development mode. In the App Review section, enable the "Do you want to make this app available to the public" check box.
  4. Note the 'App ID' provided. Pass on the 'App ID' to Facebook.
  5. Facebook will permission the 'App ID' for access to ThreatExchange.

Once you have your App ID, you can apply for access to ThreatExchange today!

UI Overview

Please see the UI Overview page.

Authenticate via an Access Token

The ThreatExchange APIs perform authentication via access tokens. After Facebook notifies you that your App can access ThreatExchange, use the access token tool to get an App Token. Please note, app tokens give access to sensitive details to your app and should be treated like a password.

With the access token, test your access to ThreatExchange by retrieving the list of members in the exchange:<access_token>

If this request does not return an error, you are now ready to begin exploring ThreatExchange!

Searching Data Using the API

With your newly activated access token, perform a search for malicious URLs added in the last week:;status=MALICIOUS&amp;since=a week ago&amp;access_token=<access_token>

Please note that not all fields are returned by default. Consult the reference documentation and specify the fields you are looking to read by appending the fields parameter. See the Graph API guide for more details.

Publishing Data Using the API

Test publish a domain,, ensuring only you are able to see the data:


description=Test data publishing

The return value will be a JSON map with a success or failure code and, if the call is successful, the unique ThreatExchange ID for the descriptor you published!

Publish a descriptor for your own domain,, and share it with Facebook's app ID, 820763734618599:


description=The domain owned by <your_app_id>

More API Examples

Search for all compromised credentials found on the Internet within the last day:;since=yesterday&amp;access_token=555|1235

Find the unique ThreatExchange ID for a specific indicator, such as;access_token=555|1235

Explore related indicators for a specific indicator with ThreatExchange ID 898557073557972:|1235

Explore all of the descriptors for a specific indicator with ThreatExchange ID 898557073557972:|1235

See more examples on our Github, or on the endpoint pages for threat indicators, threat descriptors, malware analyses, or malware families.