Vetting API - v 2.27


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 one hundred tests with geo-location 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 parameters and items 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 array.

The API posting sequence is:


Where <url> =

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

For all API calls:

  • Properly encode all values (except apikey and ip) within the 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
The API uses HTTPS POST to support over 2,000 characters for API requests.

An example of an API call:  

Documentation and Configuring

The API is supported with a JavaScript file 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. Simply download the file and include in your sign-up forms as follows:

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

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

Place the following in your signup page directly above the </body> tag (replacing 'path_to_javascript' with the local directory of the file:

<script type="text/JavaScript" src="/path_to_javascript/EHawkTalon.js"></script> 
<script type="text/javascript">
Note: do not just send the fingerprint value from the talon. Send the entire talon as we use other information within the talon JSON. Talon in your vets should look like: talon":"{\"version\":2,\"status\":0,\"timestamp\":\"Thu, 30 Oct 2014 15:57:04 GMT\",\"tz\":{\"dst\":false,\"tzo\":240,\"stzo\":240},\"lang\":\"en-US\",\"ua\":\"Mozilla\\\/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit\\\/537.36 (KHTML, like Gecko) Chrome\\\/38.0.2125.111 Safari\\\/537.36\",\"fp\":\"71574e103ebae1150032aec166d1663c\"}
If you want to track device fingerprints yourself, make sure to use the fingerprint value returned in the JSON response. In the JSON, with details=yes, you will see fingerprint":"788a4534a7c98b2666003dd39f967079". Use this value, NOT the value sent with talon, as the FP sent in talon is often changed on our servers for security and device types.

API Keywords and Parameters

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

Parameter Keyword Value
IP ip IPv4 address of the user connecting browser (required).
Email Address email email address (
Phone Number phone Phone number

Format: all NON US numbers should be proceeded by a + (must be properly encoded as %2B), no spaces, -, (), etc. Just numbers. US and Canada numbers should be in 10 digit format XXXXXXXXXX. NON US format is "+" AND country code AND number.
Street street Street, PO box, location
City city City, town, or village
State state State, province, or area. US and Canada must be two-letter lowercase code. Other countries just use the actual state if available.
Postalcode postalcode Postal code or zip code
Country country Two letter lowercase country code (ISO codes)
Domain 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 “”. Do not use URL (no http://, just “”)
Website website url of the user’s website (
Name name User’s full name in any format. We also support first_name and last_name keywords if you want to send them as individual items. Send only one type, either name or the parts but not both.
User Name username The username or userID of the account. Use this ID to link back to your unique ID on your systems.
User-Agent useragent The User-Agent string provided by the browser
Talon JS talon See EHawkTalon.js for device fingerprinting and status.
Producer or Partner ID producer_id Use this value to link vets back to a partner or lead generator
Campaign campaign campaign ID linked back to the lead or data
Ad ad Advertisement ID linked back to the lead or data
Birth Date birth_date Birth date in format YYYY-MM-DD
Details details yes / no (default)
The next release will change the default to YES
Set value to “yes” adds test area scores to the JSON. See example below.
Re-Vet revet yes / no (default)

IMPORTANT! When vetting the same person/data multiple times during a short time period, the vetting service uses activity testing to catch similar data. If you are re-vetting the same data, make sure to set revet=yes in these vets as they will bypass the activity logging.
Referrer referrer the referring url provided by the browser during form completion
Timeout timeout no / yes (default)

If timeout=no then the vetting engine will perform additional testing on domain and other areas. If you can wait up to five seconds for the API response, then add this to your API calls. If set to yes or not set then the API should return scoring in less than one second.
Blank, No Data, “none” type value - Important Note
If a parameter 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. Parameters 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 and an error array.

                                        Details of JSON
  "version": "v2.27",             | API version
  "transaction_id": "52fb265",    | unique Vet ID
  "status": 0,                    | status codes array
  "error_message": "",            | error messages array
  "score": [                      | Risk Score array
    "Risk Score",
    -13,                          | Risk Score value
    "Low Risk"                    | Risk Type
  "errors": [                     | error details array
  "scores": [                     | Empty unless details=yes

Adding parameter “details=yes” expands the JSON to include test area scoring. The Combined Score equals the Risk Score and is just a repeat of total Risk Score.

  "version": "v.27",              | API version
  "transaction_id": "52fb265",    | unique Vet ID
  "status": 0,                    | status codes array
  "error_message": "",            | error message array
  "score": [                      | Risk Score array
    "Risk Score",
    -13,                          | Risk Score value
    "Some Risk"                   | Risk Score type
  "errors": [                     | error details array
  "scores": {                     | area score array
    "ip": [                       | IP test area
      0,                          | IP Risk Score
    "location": [                 | Location Risk area
      4,                          | Location Risk Score
    "email": [                    | Email Risk area
      -4,                         | Email Risk Score
    "domain": [                   | Domain Risk area
      -15,                        | Domain Risk Score
    "geo": [                      | Geo Risk area
      2,                          | Geo Risk Score
    "combined": [                 | Combined or Total
      -13,                        | Risk Score for vet
      "Some Risk"                 | Risk Type

For customer who want more details on the risk hits and areas, they can request an additional details section for the JSON that lists all major risks by test area.

"details": {
    "ip": {
      "city": "Delhi",
      "country": "India",
      "timezone": "Asia\/Kolkata",
      "score_details": [
        "Proxy - Anonymous",
        "Bots, Drone, Worm, Proxy, TOR",
        "Spam Blacklist (E-HAWK)"
    "location": {
      "score_details": [
        "Invalid Postalcode"
    "email": {
      "score_details": [
    "phone": {
      "score_details": [
        "Fake or Invalid"
    "geo": {
      "score_details": [
        "IP vs location > 6,000 miles"
    "activity": {
      "score_details": [
        "4 Repeats"
    "community": {
      "score_details": [
        "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). 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:

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:

Parameter Keyword Value
Vet ID 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 feedback 1=too high, 2=too low, 3=correct
Reason 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: 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.

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 array with error codes and a corresponding errors array. As an example, an API call with phone and domain empty would result in:

"score":["Risk Score",-34,"High Risk"],
"errors":[["phone-valid",21,"No phone provided"],["domain-valid",23,"No domain provided"]],
Status Description
0 no error
1 invalid API version number
2 invalid customer ID
3 invalid api key
4 remote port input error
5 IP input error
6 email input error
7 phone number input error
8 street input error
9 city/town/village input error
10 state/province input error
11 country input error
12 postal/zip code input error
13 domain input error
14 name input error
15 referrer input error
16 user-agent input error
17 clustern input error
18 talon input error
19 No location data provided
20 No email data provided
21 No phone provided
22 Name not provided
23 Domain not provided
24 Country not provided
-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

// clear and setup keys and values
   $post_array = array();
// add key and value to array. 
// add a keyword and value for each item to pass in the vet
   $post_array['apikey'] = 'YourAPIKey';   
   $post_array['ip'] = ''; 
   $post_array['email'] = ''; 
   $post_array['revet'] = 'yes'; 
   $post_array['details'] = 'yes'; 

// Do the vet
$curl = curl_init("");
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

// 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 Code [updated 2014-08]
Includes PHP script, Excel data template, and files to send a batch of vetting data to the API. Returns Risk Scores and JSON responses. Great for testing the vetting api. The Excel spreadsheet has rows to paste your data into and creates the batch JSON data. Or just paste in your data and email the excel file to and we will batch process for you and let you view the results in our dashboard reporting system.