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.

API Endpoint (5.8)

https://feed-api.ehawk.net/

The API accepts both HTTPS POST and HTTPS GET.

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

CRUL 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_id=12345&reason=5

GET to delete incident

https://feed-api.ehawk.net/incident/delete?apikey=your_apikey&incident_id=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 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.

JSON Response

The response JSON will return a status code, and when adding incidents also an incident ID.

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