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 - v 4.14

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.e-hawk.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.

As an example, calling the API with CURL (see PHP example):

$ 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' https://api.e-hawk.net/

EHawkTalon.js - v4.2

The API is supported with a JavaScript Device fingerprinting file from our CDN. Incorporating this file 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": 4, "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="https://talon-ehawk.netdna-ssl.com/EHawkTalon-4.2.js"></script> 
<script type="text/javascript">
    eHawkTalon();
</script>
</body>
Tech Note: 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.
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. Please follow any value formats listed below.

Keyword Value and Format
apikey Your E-HAWK Vetting API KEY (required)
ip IPv4 address of the user connecting browser (required). IPv6 supported but IPv4 recommended.
email email address (name@tester.com)
talon See EHawkTalon.js for device fingerprinting implementation
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)
first_name First name
last_name Last name
username The unique username or userID of the account on your systems or platform.
useragent The User-Agent string provided by the browser
referrer the referring URL provided by the browser during form completion
revet true

IMPORTANT! The vetting service by default uses activity testing to tag similar data from multiple sign-ups, bots, etc. If you want to manually vet a user again within a short period of time, you should add revet=true to the API call, 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 false

If timeout=false then the vetting engine will perform additional testing on domain, email 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 400ms plus transit time.
Additional data for lead generators, marketing, and lenders
lead_id ID of lead in your lead management system
lead_source ID or name that is providing the leads.
sub_id Sub-ID or Affiliate ID. The ID of a source within the Lead Source. Requires lead_source value
campaign_id Campaign ID or name.
lead_type Example: payday, installment loan, invoice loan, sweepstakes, etc.
bank_name Bank name
bank_phone Bank phone number. US and Canada: 10 digit format XXXXXXXXXX
International: "+" AND country code AND number, ex: +33143542331
account_number Bank account number
routing_number Bank routing number
driving_license_number Driver's license number
driving_license_state Two-letter lowercase code for driver's license issue state
birth_date Birth date in format YYYY-MM-DD
social_security_number Social security number in format 123456789
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 can receive negative scores and impact the Risk Score.
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"
    ],
  }
}
Name Type Description
version string API version
transaction_id string API transaction ID
status number status code. See codes below
error_message string blank if no error, or message of error
score array risk number between -100 and +100
type string of the Risk Level
total number of the total score of all areas
area array each area tested with the score as a number
fingerprint array id string value of fingerprint
hits number of times seen in API calls
risk_hits array area arrays with all the hits for each area
{
  "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"
      ]
    },
  }
}
Name Type Description
version string API version
transaction_id string API transaction ID
status number status code
error_message string blank if no error. Message of error.
score array three elements. Item 1 is a label. Item 2 is the Risk Score (number between -100 and +100), item 3 is the Risk Type string
scores array arrays of each scoring area. Array key is area. Item 1 is a label of 'total'. Item 2 is a number value of the area score.
details array score_total number sum of all scoring
fingerprint string value
fingerprint_hits number of time fingerprint seen by system
area hits if risk hits, then they are listed for each area under score_details array
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"
}
Status Description
0 Success - no errors
5 IP input error
-1 network congestion (reduced fidelity)
-3 Invalid API key
-4 Account Suspended
-12 Out of Vetting Credits
-13 Exceeded Max API Call Rate
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="first_name">
<input type="text" name="last_name">
<input type="email" name="email">
<input type="text" name="domain">
<input type="hidden" name="talon" value='{"version": 4, "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="https://talon-ehawk.netdna-ssl.com/EHawkTalon-4.1.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'] = 'no';
   
   $post_array['first_name'] = $_POST['first_name'];   
   $post_array['last_name'] = $_POST['last_name']; 
   $post_array['email'] = $_POST['email']; 
   $post_array['domain'] = $_POST['domain'];

// Call the API
$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_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>';
}
?>