Vetting API - v 4.1

Overview

The E-HAWK Vetting service provides real-time reputation analysis, background checks and risk analysis. More than simple verification, our vetting service provides threat and risk assessments correlated across over two hundred tests and known miscreants histories. The Vetting API is used to call the vetting service during sign-up, account updates, or other interactive processes. Please follow this guide for implementation instructions.

Using HTTPS RESTful calls, your online forms or back-end systems query our service about risks levels associates with the information entered by users. Each call requires an API key and the keyworld and values to analyze. The response from the API call is a JSON array that consist of an ordered set of header information followed by a scoring arrays.

The API POST sequence is:

https://api.e-hawk.net/keyword=value

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

For all API calls:

  • Properly encode all values (except apikey and ip) within the HTTPS POST (example the “+” for international phone numbers should be sent as “%2B”). See w3school guide.
  • All values must be in UTF-8 character sets. See UTF-8.com.

Documentation and Configuring
EHawkTalon.js

The API is supported with a JavaScript file from our CDN or hosted on your local infrastructure. Incorporating this file into your sign-up process increases accuracy and provides critical data for E-HAWK vetting analysis. The code categorizes the computer, OS, time zone, etc. of the sign-up device.

Place the following in your signup page's <form> ... </form> block:

 <input type="hidden" name="talon" value='{"version": 3, "status": -1}' id="talon"> 

Place the following in your signup page directly above the </body> tag:

<script type="text/JavaScript" src="http://talon.e-hawk.net/3/EHawkTalon3.js"></script> 
<script type="text/javascript">
    eHawkTalon();
</script>
</body>

If you would like to use HTTPS via CDN then use

https://talon-ehawk.netdna-ssl.com/3/EHawkTalon3.js

To host the EHawkTalon.js locally, download the file and update the src to match the directory path to the local file.

If you want to track device fingerprints yourself, make sure to use the fingerprint value returned in the JSON response. In the JSON response you will see fingerprint":"788a4534a7c98b2666003dd39f967079". Use this value, NOT any values sent with talon, as the values sent in talon often change on our servers.

API Keywords, Values, and Formats

The Vetting API will analyze the following input values to calculate a Risk Score. With the exception of the apikey and ip values, all inputs are optional (see note on Blank or No Data below). However, the more keyword and value pairs provided, the better the analysis. Keywords must be lowercase.

To help with implementation, you can send test API POST to http://www.e-hawk.net/support/api-call-verify.php. The page tests the keywords and values for the correct formats.

Keyword Value and Format
apikey Your E-HAWK Vetting API KEY (required).
ip IPv4 address of the user connecting browser (required).
email email address (name@tester.com)
talon See EHawkTalon.js for device fingerprinting implimentation.
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 verified domain. Not necessarily the domain of their email, but the domain they own or will be sending email from. Domain should be linked to their business or “From” address of their emails. Example “e-hawk.net”. Do not use URL (no http://, just “www.domain.com”)
website url of the user’s website (http://www.mysite.com)
name User’s full name, First Last format
username The username or userID of the account. Use this ID to link back to your unique ID on your systems.
useragent The User-Agent string provided by the browser
producer_id Use this value to link vets back to a partner or lead generator
referrer the referring URL provided by the browser during form completion
revet yes

IMPORTANT! The vetting service by default uses activity testing to tag similar data from multiple sign-ups, bots, etc. and mark as high risk. If you want to manually vet a user again within a short period of time, you should add revet=yes to the vet, so it bypasses the activity engine. Otherwise our system will think the person is trying to sign-up multiple times and start marking that user as high risk.
timeout no

If timeout=no then the vetting engine will perform additional testing on domain and other areas. If you can wait up to four seconds for the API response, then add this to your API calls. If not set then the API should return scoring in less than 500ms.
Blank, No Data, “none” type value - Important Note
If a keyword is supplied in the API call with no value, or blank, or even a holder value such as “none” or “n/a”, then the Vetting service treats this as suspicious, will score the area negatively, and list the error in the API response. We recommend mandatory fields in forms should be vetted, and optional fields should only be vetted when completed by users. Keywords with no data/empty/placeholders will receive negative scores and impact the Risk Score.

JSON Response

The standard output is a JSON array that contains a header followed by the Risk Score array, an error array, area score array, and risk hit details array.

{
  "version": "v.3",              | API version
  "transaction_id": "52fb265",    | unique Vet ID
  "status": 0,                    | status code
  "error_message": "",            | error message array
  "score": [                      | Risk Score array
    "Risk Score",
    -100,                         | Risk Score value
    "Very High Risk"              | Risk Score type
  ],
  "errors": [                     | error details array
    
  ],
  "scores": {                     | area score array
    "ip": [                       | IP test area
      "total",
      -250,                       | IP Risk Score
      ""
    ],
    "email": [                    | Email Risk area
      "total",
      -135,                       | Email Risk Score
      ""
    ],
    "community": [                | Community Risk area
      "total",
      -80,                        | Community Risk Score
      ""
    ],
    "geolocation": [              | Geo Risk area
      "total",
      -65,                        | Geo Risk Score
      ""
    ],
    "activity": [                 | Activity Risk area
      "total",
      -65,                        | Activity Risk Score
      ""
    ],
    "combined": [                 | Combined or Total
      "total",
      -100,                       | Risk Score for vet
      "Very High Risk"            | Risk Type
    ]
  },
  "details": {
    "ip": {
      "city": "Delhi",
      "country": "India",
      "timezone": "Asia\/Kolkata",
      "score_details": [
        "Proxy - Anonymous",
        "Bots, Drone, Worm, Proxy, TOR",
        "Spam Blacklist"
      ]
    },
    "fingerprint": "12e30087109e44e4fd4"
    },
    "email": {
      "score_details": [
        "Disposable"
      ]
    },
    "geolocation": {
      "score_details": [
        "IP vs location > 6,000 miles"
      ]
    },
    "activity": {
      "score_details": [
        "4 Repeats"
      ]
    },
    "community": {
      "score_details": [
        "Fraud",
        "Cyber Crime"
      ]
    },
  }
}



Risk Score and Risk Type

Risk Score is computed by correlating proprietary data, community data, trends, and other weightings across the entire data set of the API call. The Risk Score can range from +100 (lowest risk) to -100 (highest risk). Risk areas can score any value, and on some very high risk vets, certain areas will score -300 or worse.

Each vetting score starts at zero. When our risk engine discovers good things, such as a clean IP, the vet gets a few positive points. When bad things are identified such as a history of spam, negative points are scored. Total Risk Score is based on proprietary algorithms correlated across over two hundred fifty areas of analysis.

Risk Score Levels and Types
Your company can decide what risk scores trigger review or action. As a basic guide, we have provided the following chart. Risk hit scores can be customized in the portal. As an example, tagging a proxy or bot usually results in a very high risk vet score, but each customer can customize these scores to fit their business risk profile.

Type Risk Score
Lowest Risk 10+ or higher
Low Risk 0 to 9+
Some Risk -1 to -15
Medium Risk -16 to -30
High Risk -31 to -70
Very High Risk -71 to -100

API Feedback – Let us know if the Risk Score is Good or Bad

If you vet data and want to provide feedback to our service, please use the same API call as when vetting, but with the following parameters:

Keyword Value
vetid Value of the vetting ID returned in the original vet call. If you do not have the original vetting ID, just use zero (0) for vetid and try to provide as much information as possible on the vet and values into the “reason” area.
feedback 1 too high, 2 too low, 3 correct
Reason Free form text to explain why and what was wrong on the vet.

For example, to register feedback that vet ID 123 was too high (+10 and should have been negative because of a bad email), send the following to the API:

https://api.e-hawk.net/?apikey=key&vetid=123&feedback=1&reason= the%20email%20address%20is%20bad

An example without knowing the vet ID, would look like the following with the actual email address listed in the notes.

https://api.e-hawk.net/?apikey=key&vetid=0&feedback=1&reason= email%20address%20of%20sample%40e-hawk.net%20is%20bad

After your feedback has been successfully recorded, you will receive a confirmation of: {"response":"Feedback Added"}. This feedback is reviewed weekly and will not impact scores for a while.


Status and Error Codes

The status will be a value (0 = OK) or an error code and a corresponding errors array. As an example, an API call invalid API KEY would return

{
 "version":"v3.1",
  "transaction_id":"554bd0e5512a07.64037099",
  "status":-3,
  "error_message":"Invalid API key",
  "score":[],
  "errors":[],
  "scores":[]}
}
Status Description
0 Success - no errors
3 invalid api key
5 IP input error
-1 network congestion (reduced fidelity)
-12 Out of Vetting Credits
-13 Exceed Max calls per Second

Sample and Batch Code

Sample CURL API call in PHP
To help with implementation, you can send the API POST to http://www.e-hawk.net/support/api-call-verify.php. The page tests the parameters and values for the correct formats.

<?php 
// clear and setup keys and values
   unset($post_array);
   $post_array = array();
   
// add a keyword and value for each item to pass in the vet
   $post_array['apikey'] = 'YourAPIKey';   
   $post_array['ip'] = '10.1.1.1';       
   $post_array['email'] = 'me@example.com'; 
   $post_array['domain'] = 'example.com';
   $post_array['talon'] = $_POST['talon'];  
   $post_array['revet'] = 'yes'; 
   $post_array['timeout'] = 'no';  

// Do the vet
$curl = curl_init("https://api.e-hawk.net/");
if (!empty($curl)) {
    curl_setopt ($curl, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt ($curl, CURLOPT_POST, true);
    curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt ($curl, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt ($curl, CURLOPT_CONNECTTIMEOUT, 20);
    curl_setopt ($curl, CURLOPT_TIMEOUT, 10);
    curl_setopt ($curl, CURLOPT_USERAGENT, "E-HAWK VET");
    curl_setopt ($curl, CURLOPT_POSTFIELDS, $post_array);
    $result = curl_exec ($curl);
    curl_close ($curl);
}              
               
// print result
print_r($result); 

// process result
$vet_array = json_decode($result, true);    
echo '<p>Risk Score = '.$vet_array['score'][1].'<br>';
echo 'Risk Type = '.$vet_array['score'][2].'<br></p>';
?>     

PHP Vetting API Batch Process [updated 2015-05]
Download the Excel spreadsheet, paste in your data, and email support@e-hawk.net requesting a batch processing. We will provide a secure file upload area to send your Excel file, process the data, and let you view the results in our dashboard reporting system.