Community 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 Community 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.
A Special Community API Key is required to add to the Community. Please email support if interested.
API Endpoint (5.18)
https://feed-api.ehawk.net/
The API accepts both HTTPS POST and HTTPS GET, but recommended is POST if you are submitting multiple data points.
For GET use the format:
https://feed-api.ehawk.net/function/?keyword=value
When using POST, make sure to have Content-Type: application/x-www-form-urlencoded
CURL POST API call example:
$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'apikey=your_apikey' https://feed-api.ehawk.net/function/
Function
Options for function
reason/list to get a JSON of all possible reasons. These codes are required when sending data to the API. GET and POST calls supported. GET example:
https://feed-api.ehawk.net/reason/list?apikey=your_apikey
incident/set Incidents are groups of items that are linked together to define a fraudster. For example, if there are three IPs and an email address that a specific 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.
A POST example adding IP 10.0.1.1, email me@test.com with reason = 1:
$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'apikey=your_apikey&ip=10.1.1.1&email=me@test.com&reason=1' https://feed-api.ehawk.net/incident/set/
phone/set
email/set
ip/set
domain/set
fingerprint/set
To add individual data on items such as phone, email, IP, domain, and fingerprint. GET for adding a single IP with reason=1:
https://feed-api.ehawk.net/ip/set?apikey=your_apikey&ip=10.1.1.1&reason=1
CURL for adding a single email with reason=1
$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'apikey=your_apikey&email=me@test.com&reason=1' https://feed-api.ehawk.net/email/set/
The API also supports sending multiple items and types in a single call. For example to send three IPs and two emails,
you just make the items an array using brackets [] after the type name:
$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'apikey=your_apikey&ip[]=10.0.1.1&ip[]=10.0.1.2&ip[]=10.0.1.3&email[]=abc@example.com&email[]=def@example.com&email[]=hij@example.com&reason=1' https://feed-api.ehawk.net/incident/set/
incident/update incident/delete for changing the reason or removing an incident.
GET to change incident reason from 1 to 5:
https://feed-api.ehawk.net/incident/update?apikey=your_apikey&incident=12345&reason=5
GET to delete incident
https://feed-api.ehawk.net/incident/delete?apikey=your_apikey&incident=12345
To update individual items added with item functions, just resubmit the items with a new reason or reason=99 to delete.
https://feed-api.ehawk.net/ip/set?apikey=your_apikey&ip=10.0.1.10&reason=99
Keywords
Use function with keywords and value pair(s) with a single required reason
Keyword | Value and Format |
---|---|
apikey | Your API key REQUIRED |
ip | IP address. IPv4 or IPv6. |
email address (name@tester.com) | |
domain | a domain (tester.com) |
phone | US and Canada: 10 digit format XXXXXXXXXX International: "+" AND country code AND number, ex: +33143542331 (France phone) |
name | Full name |
fingerprint | The Talon device fingerprint returned in the JSON from the Vetting API call |
reason | Number from 1 to 1000. The reason value from the list using reason/list REQUIRED |
Each call can have only one reason, but you can send up to 50 keyword/values per call. If sending large data amounts to the API, we recommend using POST as GET truncates at 2,048 characters.
The API will automatically remove bogus and improperly formatted values, while adding any data that conforms to the specs. If for example you send two IPs where one is in the proper format and the other is not, only the proper one will be added. No error will be given in the JSON response as long as one value is accepted.
JSON Response
The response JSON will return a status code, and when adding incidents also an incident ID.
{ "incident_id": "17556", "response": "Ok", "status": 200 }
Status Codes
Status | Response |
---|---|
200 | OK. Added properly formatted data point(s) |
404 | A valid type is required |
502 | Errors with data. Invalid, no valid values provided, no reason |
-6 | IP not in ACL |
{ "response": "reason is required", "status": 502 }