Community Feed API

Overview

Leveraging community information on known spam, phishing, identity theft, and cyber criminals gives the community and our customers the best chance for rapid identification and stopping fraudsters from being able to inflict damage on multiple organizations. The feed-api makes it easy to add your data on fraudsters such as phone numbers, email, domains, IPs, and other information to our community database. You can add a group of data (several items that together define a fraudster) with a single post using “Incidents” or add individual elements (such as a known bad IP) with direct calls. Please follow this guide for implementation instructions.

API Calls (4.18)

Adding data to the community is done using the FEED API POST sequence:

https://feed-api.e-hawk.net/apikey/function/?keyword=value

The API uses Content-Type: application/x-www-form-urlencoded

The API requires HTTPS POST to support over 2,000 characters for API requests.

Reason List

Use the function reason/list to get a JSON of all possible reasons. You will need these codes when sending data to the API.

https://feed-api.e-hawk.net/apikey/reason/list/
Add Incident - Group Data

Incidents are groups of items that are linked together to define a fraudster. For example, if there are 3 IPs and an email address that a certain fraudster uses, submit all four items as an Incident to group the data together. You should also use the Incident submission for all fraudster accounts items such as email, IP, address, name, domain, and/or phone into a single record.

Function: incident/set

Keyword Value and notes
ip IPv4 address of the user connecting browser (required).
email email address (name@tester.com)
phone US and Canada: 10 digit format XXXXXXXXXX
International: "+" AND country code AND number, ex: +33143542331
street Street, PO box, location
city City, town, or village
state State, province, or area. US and Canada must be two-letter lowercase code. Other countries just use the actual state if available.
postalcode Postal code or zip code
country Two letter lowercase country code (ISO codes)
domain User’s domain
emaildomain User’s email domain
fingerprint Device fingerprint that is returned in the JSON from the Vet. As an example, in the JSON look for "fingerprint":"XXX"
reason REQUIRED. Number from 1 to 1000. The reason value from the list using reason/list API call

Incidents can include single or multiple data points on any or all variables. Invalid data (such as country input that has more than two characters or does not match a proper country code) is removed from the incident automatically. Properly formatted incident reports will return:

 {"status":200,"response":"Ok"} 

Incidents with Multiple Items of the Same Kind
Example with multiple IPs:

$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'ip[]=1.1.1.1&ip[]=1.1.1.2&reason=2'  https://feed-api.e-hawk.net/apikey/incident/set/

Note that for multiples items of the same keyword, you must send as an array using [] brackets.

Incidents must contain a minimum of two, unique data points (such as two IPs, or an IP and an email) and a reason. If the incident post does not meet the minimum requirements you will receive an error message (below), or the incident will just be processed as Individual Data.

 {"status":502,"response":"Not enough variables provided"}

You can re-submit an incident (data values must be identical to original incident report) to mark it as current or update the reason. For example, re-submit the incident and change reason to 99 if the user has stopped being bad.


Add Individual Data

To add individual data on items such as phone, email, domain, and IP, just use a function below with a reason.

Function Variables Required
phone/set phone, reason
email/set email, reason
emaildomain/set emaildomain, reason
ip/set ip, reason
domain/set domain, reason
fingerprint/set fingerprint, reason