Vetting API

Overview

The E-HAWK Vetting service provides real-time reputation and risk analysis. The Vetting API is used to call the vetting service during sign-up, account updates, logins, or other user interactions. Please follow this guide for implementation instructions.

API Endpoint (5.9)

Using HTTPS RESTful calls, your online forms or back-end systems query our service about risks levels associated with the information entered by users.

The API requires HTTPS POST and Content-Type: application/x-www-form-urlencoded

For all API calls:

• Data is sent with name/value pairs keyword=value
• Properly encode all values within the HTTPS POST.
• All values must be in UTF-8 character sets.
• x-www-form-urlencoded does not support boolean, so all true/false settings must be strings

As an example, calling the API with CURL (see PHP example and POSTMAN testing below):

Keywords

The Vetting API will analyze the following input values to calculate a Risk Score. Every API call requires the apikey and a minimum of ip, email, or domain values. However, the more keyword and value pairs provided, the better and more detailed the analysis. Keywords must be lowercase. Please follow value formats listed below.

E-HAWK Talon

The API is supported with a JavaScript Device fingerprinting technology. Incorporating this into your sign-up process increases accuracy and provides extra data for E-HAWK analysis.

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

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

Place the following in your web page directly above the </body> tag and the last item on the page:

<script type="text/JavaScript" src="path_to_your_talon_js_file.js"></script> 
<script type="text/javascript">
    eHawkTalon();
</script>
</body>

Download Talon JS (v5.8 updated May, 2020) in the portal and add to your JS files or CDN. Make sure to execute the eHawkTalon(); after the DOM (document) is finished loading. It is important that all fonts and other DOM modifications scripts are executed and ready before the talon is run.

JSON Response

The output returned by an API call is in JSON format. There are two response formats that can be selected in the Portal Settings area: Format 2 (new and compact) and Format 1 (original).

{
  "version": "5.9",
  "transaction_id": "5808be52e52542.29287853",
  "status": 0,
  "error_message": "",
  "score": {
    "risk": -100,
    "type": "Very High Risk",
    "total": -418
  },
  "area": {
    "ip": -80,
    "email": -155,
    "phone": 5,
    "domain": 0,
    "geolocation": -24,
    "community": -139,
    "fingerprint": -25
  },
  "fingerprint": {
    "id": "15da7f7b71f17e237ff9197e19802399",
    "hits": 4
  },
  "risk_hits": {
    "ip": [
      "Proxy - Anonymous",
      "Spam Blacklist"
    ],
    "email": [
      "Disposable",
      "Emaildomain Age 1 to 5 Days"
    ],
    "geolocation": [
      "IP vs location > 6,000 miles"
    ],
    "activity": [
      "4 Repeats"
    ],
    "community": [
      "Fraud Email",
      "Cyber Crime IP"
    ]
  }
}

{
  "version": "v.4", 
  "transaction_id": "5808be52e52542.29287853", 
  "status": 0,  
  "error_message": "",  
  "score": [     
    "Risk Score",
    -100,       
    "Very High Risk"  
  ],
  "scores": {   
    "ip": [     
      "total",
      -250
    ],
    "email": [    
      "total",
      -135
    ],
    "community": [  
      "total",
      -80
    ],
    "geolocation": [ 
      "total",
      -65
    ],
    "activity": [  
      "total",
      -65
    ]
  },
  "details": {
    "score_total": -595,
    "fingerprint": "12e30087109e44e4fd4",
    "fingerprint_hits": 3,
    "ip": {
      "score_details": [
        "Proxy - Anonymous",
        "Bots, Drone, Worm, Proxy, TOR",
        "Spam Blacklist"
      ]
    },
    "email": {
      "score_details": [
        "Disposable"
      ]
    },
    "geolocation": {
      "score_details": [
        "IP vs location > 6,000 miles"
      ]
    },
    "activity": {
      "score_details": [
        "4 Repeats"
      ]
    },
    "community": {
      "score_details": [
        "Fraud Email",
        "Cyber Crime IP"
      ]
    },
  }
}

Status Codes

The status will be a value (0 = OK) or an error code and a corresponding errors array. Your script should check for status = 0 for a valid API call and response. As an example, an API call with an invalid apikey would return

{
 "version":"5.9",
  "transaction_id":"123456789",
  "status":-3,
  "error_message":"Invalid API key"
}

Sample CURL API call in PHP

First, create a web form (form.php) that captures information to send to the API. Here we capture some data such as first and last name and email. We also capture in hidden fields IP, useragent, and talon. Note that the POST values need to match the form name values. When submitted, the form action sends the names and values to 'process.php' that calls the API and processes the scoring and response.

<!-- Sample Form "form.php" - PHP File -->
<form action="process.php" method="POST">
<input type="text" name="firstname">
<input type="text" name="lastname">
<input type="email" name="email">
<input type="hidden" name="talon" value='{"version": 5, "status": -1}' id="talon">
<input type="hidden" name="ip" value="<?PHP echo $_SERVER['REMOTE_ADDR'];?>"/>
<input type="hidden" name="useragent" value="<?PHP echo $_SERVER['HTTP_USER_AGENT'];?>" />
<input type="submit" value="Submit">
<form>  

<script type="text/JavaScript" src="js/EHawkTalon.js"></script> 
<script type="text/javascript">
    eHawkTalon();
</script>

<?php
// process.php file 
// clear and setup keys and values
   unset($post_array);
   $post_array = array();
   
// add a keyword and value for each item to pass in the API call
// the $post_array names should match E-HAWK keywords
// the $_POST values should match the form names exactly
   $post_array['apikey'] = 'your_apikey';   
   $post_array['ip'] = $_POST['ip'];    
   $post_array['useragent'] = $_POST['useragent'];  
   $post_array['talon'] = $_POST['talon'];      
   
   $post_array['firstname'] = $_POST['firstname'];   
   $post_array['lastname'] = $_POST['lastname']; 
   $post_array['email'] = $_POST['email']; 
   
   // if no domain owned by user, then grab from emaildomain: 
   $post_array['domain'] = substr(strrchr($_POST['email'], "@"), 1);

// Call the API using CURL
$curl = curl_init("https://api.ehawk.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_CONNECTTIMEOUT, 10);
    curl_setopt ($curl, CURLOPT_TIMEOUT, 10);
    curl_setopt ($curl, CURLOPT_USERAGENT, "E-HAWK API Call");
    curl_setopt ($curl, CURLOPT_POSTFIELDS, $post_array);
    $result = curl_exec ($curl);
    curl_close ($curl);
}              
               
// print result option - remove after testing
print_r($result); 

// process result
$response_array = json_decode($result, true);    

// check if API response contains status and responded
if (isset($response_array['status'])) {
    // check for status value success or error
    if($response_array['status'] == '0' ) {
      // check for JSON response format 1 or 2
      // JSON Format 1
      if(isset($response_array['scores'])) {
        echo '<p>Risk Score = '.$response_array['score'][1].'<br>';
        echo 'Risk Type = '.$response_array['score'][2].'</p>'; 
        }
      // JSON Format 2  
      if(isset($response_array['area'])) {
        echo '<p>Risk Score = '.$response_array['score']['risk'].'<br>';
        echo 'Risk Type = '.$response_array['score']['type'].'</p>'; 
        }  
    } else {
        echo '<p>API Status Error: '.$response_array['error_message'].'</p>';
    }
} else {
    // API did not respond properly. Probably a timeout issue
    // Recommend trying to send API call again
    echo '<p>Did not get a proper response from API</p>';
}
?>

Postman Example

You can test the Vetting API using Postman. Make sure to set post variables as Body and x-www-form-urlencoded.