Vetting API - v 4.9

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

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

For example, to send an ip and email to the vetting API:

https://api.e-hawk.net/?apikey=APIKEY&=ip=10.0.1.1&email=test@example.com

EHawkTalon.js - v3.1

The API is supported with a JavaScript Device fingerprinting 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 sign-up page's <form> ... </form> block:

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

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

<script type="text/JavaScript" src="https://talon-ehawk.netdna-ssl.com/3.1/EHawkTalon3.1.js"></script> 
<script type="text/javascript">
    eHawkTalon();
</script>
</body>

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

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 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)
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
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, 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 500ms.
Additional data for lead generators and lenders
producer_id ID for lead generator who is sending the lead.
lead_type payday installment loan invoice loan other
minimum_price Minimum sale price for the lead.
site Optional field which can be used for tracking purposes.
source Optional field which can be used for tracking purposes.
campaign Optional field which can be used for tracking purposes.
ad Optional field which can be used for tracking purposes.
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 Driving license number
driving_license_state Two-letter lowercase code for driving license issue state
birth_date Birth date in format YYYY-MM-DD
social_security_number Social security number in format 123456789
monthly_income Monthly income from the loan application in USD
loan_amount Requested loan amount in USD
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 the vetting information in the format:

  • version string API version number
  • transaction_id string unique id of API call
  • status number see status and error codes
  • error_message string
  • score array risk score array
  • scores array scores for testing areas
    • score area string
    • title string
    • score number risk score for the area
  • details array risk hit details
    • fingerprint string device fingerprint
    • risk area details array
      • score_details array

An example JSON response (Type 2).

{
  "version": "v.4", 
  "transaction_id": "XXX", 
  "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": {
    "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"
      ]
    },
  }
}

Response Type 1 has an extra empty value after each scores area (scores-> area[2].

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":"v4",
  "transaction_id":"XXX",
  "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 Code, Tools, and Batch Files

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 does the vet.

           
<form action="process.php">
<input type="text" name="name">
<input type="email" name="email">
<input type="text" name="domain">
<input type="hidden" name="talon" value='{"version": 3, "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="http://talon.e-hawk.net/3.1/EHawkTalon3.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 vet
// 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['revet'] = 'no';     
   $post_array['timeout'] = 'no';
   
   $post_array['name'] = $_POST['name'];   
   $post_array['email'] = $_POST['email']; 
   $post_array['domain'] = $_POST['domain'];

// 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);    

// check if API response contains status and responded
if (isset($vet_array['status'])) {
    // check for status value success or error
    if($vet_array['status'] == '0' ) {
        echo '<p>Risk Score = '.$vet_array['score'][1].'<br>';
        echo 'Risk Type = '.$vet_array['score'][2].'</p>';
    } else {
        echo '<p>API Status Error: '.$vet_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>';
}

Posting Test Page
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 Vetting API Batch Process [updated 2016-01]
Download the Excel spreadsheet and follow the instructions in the file to securly send us the data. E-HAWK will process your file and let you view the results in our dashboard reporting system.