Loading...
EHAWKEHAWK
Request Trial

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 send 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
Always Score Good will add 5,000 points and the total score will always be 100 or greater
Always Score Bad will subtract 5,000 points and the total score will always be -100 or less

Endpoint (6.3)

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

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/tag/function/

Functions

Select a function:

set
Add, update, or delete tags

list
Returns 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

Keywords

Use function set with keywords and value pair(s) with a single required reason to add tag items.

Keyword Value and Format
apikey Your E-HAWK Vetting API KEY (required)
ip IP address. IPv4 or IPv6.
email * email address (name@example.com)
emaildomain * email domain (example.com) Does not support subdomains
domain * a domain (example.com) or subdomain (abc.example.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. 'always good' or 'always bad' tag not supported
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)
aba Bank routing number. In US this is the ABA
reason bad  good  do not score  always good  always bad  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.

Reports and Paging

Use function list followed by a required keyword 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 reporting API supports a username filter, so to limit the call above to only return tags added by the portal user of name@example.com:

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

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

{
  "response": {
    "items": {
      "ip": {
        "10.0.1.2": "bad",
        "127.0.0.1": "bad"
      }
    }
  },
  "status": 200
}

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

JSON Response

The returned JSON when adding item(s) with a count of items actually added in response :

{
    "response":"Ok - added 3",
    "status":200
}

Status Codes

Status Response
200 OK (no errors)
-6 IP not in ACL
404 A valid type is required
502 Errors with data. Invalid, no valid values provided
Top