Tag API

Overview

Tagging is used to score specific emails, emaildomains, domains, names, IPs, TLDs, CIDRs, and device fingerprints as good, bad, or to skip scoring. Items tagged as Bad will add negative scoring to the risk area, Good tags add positive scoring, and Do Not Score will set the item score to zero. Good and Bad scoring is incremental to standard area scoring and the amount can be set in your scoring profile. Tags can be managed in the Customer Portal or by using the Tag API.

To illustrate how tagging works, if you vet IP = 10.1.1.1, the vet will hit "Private or no geo IP" risk and score -10 (default scoring) for IP area. Adding tags of:

Bad will add -130 to the IP score area, and the IP will now score -140
Good will add +130 to the IP scoring area, and the IP will now score +120
Do Not Score will set the IP scoring to 0

API Endpoint (5.8)

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

The API accepts both HTTPS POST and HTTPS GET.

For GET use the format:

https://feed-api.ehawk.net/tag/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/tag/function/

Function

Options for function

Select the action to take using function values:

set to add, update, or delete tags

list to get reports on existing tags

As an example, using GET to add an IP as Bad:

https://feed-api.ehawk.net/tag/set?apikey=your_apikey&ip=127.0.0.2&reason=bad

Add, Update, Delete Tags

Use function set with keywords and value pair(s) with a single required reason

Keyword Value and Format
apikey Your E-HAWK Vetting API KEY (required)
ip IP address. IPv4 or IPv6.
email email address (name@tester.com)
emaildomain email domain (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
tld Top Level Domain. TLD tags will test against both emaildomain and domain. If you add 'xxx' as a TLD, both 'test@example.xxx' and 'www.example.xxx' will be tagged.
cidr CIDR supports /24 to /31 only. Example: x.x.x.0/24
countrycode Two letter lowercase country code (example us=United States)
reason good  bad  do not score  delete  (one required)

For example, to tag IP 127.0.0.2 as bad using CURL:

$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'apikey=your_apikey&ip=127.0.0.2&reason=bad' https://feed-api.ehawk.net/tag/set/

The API also supports sending multiple items and types in a single call. For example, to add good tags for two IPs and a domain, 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[]=1.1.1.1&ip[]=1.1.1.2&domain=ehawk.net&reason=good' https://feed-api.ehawk.net/tag/set/

Or using GET

https://feed-api.ehawk.net/tag/set?apikey=your_apikey&ip[]=1.1.1.1&ip[]=1.1.1.2&domain=ehawk.net&reason=good

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.

Tag Reports

Use function list followed by a required keywords and optional reason

For example, a GET to return a list of all IPs that are tagged Bad:

https://feed-api.ehawk.net/tag/list/?apikey=your_apikey&type=ip&reason=bad

And a CURL call for the same report:

curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'apikey=your_apikey&type=ip&reason=bad' https://feed-api.ehawk.net/tag/list/

The report is returned in JSON format with a maximum of 500 items.

Report Paging

Report Tag API calls are limited to 2,000 rows, 500 by default. Use optional paging commands to page through large data sets.

page Default page starts at 1. Increase for each additional block of records. For example, for page 10

https://feed-api.ehawk.net/report/tag/list/?apikey=your_apikey&type=ip&reason=bad&page=10

num number of records returned. Default is 500 and max is 2,000.

https://feed-api.ehawk.net/report/tag/list/?apikey=your_apikey&type=ip&reason=bad&num=2000

Status Codes

Status Response
200 OK (no errors)
404 A valid type is required
502 Errors with data. Invalid, no valid values provided