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 users interactions. Please follow this guide for implementation instructions.

API Call (5.6)

Using HTTPS RESTful calls, your online forms or back-end systems query our service about risks levels associated with the information entered by users. Each call includes keyword and values pairs to analyze.

The API POST sequence is:

https://api.ehawk.net/?keyword=value

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

For all API calls:

• Properly encode all values within the HTTPS POST. See w3school guide.
• All values must be in UTF-8 character sets. See UTF-8.com.
• 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), also see POSTMAN testing:

$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'apikey=YOUR_apikey&ip=10.1.1.1&email=me@test.com&country=us&timeout=false' https://api.ehawk.net/

EHawkTalon.js

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="your_js_dir"></script> 
<script type="text/javascript">
    eHawkTalon();
</script>
</body>

API Keywords, Values, and Formats

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.

Additional data for lead generators, marketing, and lenders

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 1 (original) and Format 2 (new and compact).

{
  "version": "v4",
  "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 and Error 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":"v4",
  "transaction_id":"123456789",
  "status":-3,
  "error_message":"Invalid API key"
}

Sample PHP Code

Sample CURL API call in PHP
First, create a web form that captures information to send to the API. Here we capture some data such as name, email, domain, talon, ip, and useragent. 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 - HTML File -->
<form action="process.php">
<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'] = 'YourAPIKey';   
   $post_array['ip'] = $_POST['ip'];    
   $post_array['useragent'] = $_POST['useragent'];  
   $post_array['talon'] = $_POST['talon'];      
   $post_array['timeout'] = 'false';
   
   $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
$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
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>';
}
?>