Auto

A RESTful API to store and access enhanced click data.

Metadata:

You can access the metadata by going to the following URL:

https://ec.katch.com:9044/metadata

Security and Information

The API is available to the public, please be aware of the following:

  • Only secure connections using https will be accepted.

  • If we undergo a DDoS attack the service will be shut down.
  • We store parameters as they come; we do not provide validations nor XSS verification.
  • EC Tokens generated will only return data for a period of 24 hours, after that the data is lost.

What can the Enhanced Clicks API do?

Enhanced clicks enables you to pre-populate any information about the consumer in your flow, which may have already been collected by one of our partners. The API allows for retrieving lead data with an {ectoken} parameter.

Parameter Description Example
&ectoken={ectoken} This token is a lead identifier, passed to you on the click of the URL in the Katch Listings. &ectoken=3c0cd5ac-0f38-4ee2-9ccc-e0a9ebc65661

Step #1

Collect ectoken

Append {ectoken} parameter to your campaign URL.
Example:

http://www.landingpage.com/?{Other_Parameters}&ectoken={ectoken}

Step #2

Call the EC API with ectoken

Once you are capturing {ectoken} in your URL, pass the token to our API.
PIILookupRequest is a REST endpoint used to retrieve the lead data.

Verb: GET
Route: /enhanced/pii/{ectoken}
Name Parameter Data Tipe Required Description
ectoken path Guid Yes Token returned on the store service.

Formats:

• JSON
• XML

GET + JSON

SAMPLE REQUEST URL TO EC API:

https://ec.katch.com:9044/enhanced/pii/{ectoken}?format=json

Request Body

{"ectoken":"3c0cd5ac-0f38-4ee2-9ccc-e0a9ebc65661"}

Sample Request Response

{"FirstName":"John","LastName":"Doe","Email":"jdoe@katch.com","Address1":"2481 Rosecrans Ave","Address2":"Suite 400","City":"Los Angeles","State":"CA","Phone":"310-906-5453","GenderDriver1":"0", "MaritalStatusDriver1":"1","CreditRatingDriver1":"2","Vehicle1Year":"2004","Vehicle1YearlyMiles":"20,000","Vehicle1Make":"24","CurrentlyInsured":"1"}

Auto Lead Fields

See Lead Fields and Values here.

Step #3

Setting Up Your Pages

After retrieving lead data from EC API, you can pre-populate information about the consumer.
Add .js code to every webpage of your flow.

<script type="text/javascript" src="https://api-ec-imp.katch.com/js/enhanced.demo.js"></script>

The following is a sample .js code implementation.


var KT_Helper = {
populateFinished: true,
elemID: '',
prefilledElems: {},
/**
* VALIDATES THE ECTOKEN
* @param{String} key The ectoken that will be used to retrieve the leadData
* @return{Boolean} Indicates if the ectoken is valid
*/
isValidKey: function(key) {
return true; //!(!key || /^\s*$/.test(key) || key.length != 36 || !(/^[0-9A-F\-]{36}$/.test(key)) );
},
/**
* GUP = GET URL PARAMETER
* @param {String} name The name of the parameter URL parameter
* @return {String} The value of the parameter searched
*/
gup: function(name) {
name = name.replace(/[\[]/, "\\\[").replace(/[\]]/, "\\\]");
var regexS = "[\\?&]" + name + "=([^&#]*)";
var regex = new RegExp(regexS);
var results = regex.exec(window.location.href);
if (results == null)
return "";
else
return results[1];
},

/**
* VALIDATES IF LOCAL STORAGE IS AVAILABLE (AND ENABLED)
* @return {Boolean}indicates whether local storage can be used or not
*/
isLocalStorageAvailable: function() {
var test = 'test';
try {
localStorage.setItem(test, test);
localStorage.removeItem(test);
return true;
} catch (e) {
return false;
}
},

/**
* CAPITALIZES THE FIRST CHARACTER OF AN STRING
* @param {String} string The string to change
* @return {String} The original string with the first character capitalized
* */
capitaliseFirstLetter: function(string) {
return string.charAt(0).toUpperCase() + string.slice(1);
},

/**
* LOADS A JAVASCRIPT FILE AND EXECUTES IT
* @param {String} file The URL of the file to load
* @param {Function} callback A function to be executed after the scripts loads
* @param {Function} errorCallback A function to be executed if an error occurs
* @return N/A
*/
include_js: function(file, callback, errorCallback, extraparam) {
var sc = document.getElementsByTagName("script"),
html_doc,
js,
done = false,
queue;

for (var x in sc) {
js = sc[x];
if (js.src != null & amp; & amp; js.src.indexOf(file) != -1 & amp; & amp; typeof callback === "function") {

if (js.readyState === "loaded" || js.readyState === "complete") {
// READY TO USE
if (typeof extraparam !== null & amp; & amp; typeof extraparam !== 'undefined')
callback(extraparam);
else
callback();

return true;
} else {
// WAIT FOR IT
break;
}
}
js = null;
}
// If the script is not already loaded then load it
if (js === null) {
html_doc = document.getElementsByTagName('head')[0];
js = document.createElement('script');

js.setAttribute('type', 'text/javascript');
js.setAttribute('src', file);
try {
html_doc.appendChild(js);
} catch (ex) {
if (window.console !== undefined) {
console.log('Debug: Warning! Request for ' + file + ' failed. Reason: ' + ex);
}

if (typeof errorCallback === 'function') {
errorCallback();
return true;
}
}
}

js.onload = js.onreadystatechange = function() {
var item, i, queue;

if (!done & amp; & amp;
(!js.readyState || js.readyState === "loaded" || js.readyState === "complete")) {
done = true;
js.onload = js.onreadystatechange = null;

if (js & amp; & amp; js.parentNode & amp; & amp; typeof callback === "function") {
if (typeof extraparam !== null & amp; & amp; typeof extraparam !== 'undefined')
callback(extraparam);
else
callback();
return true;
}
}
};

return false;
},

getFileNameURL: function() {
//this gets the full url
var url = document.location.href;
//this removes the anchor at the end, if there is one
url = url.substring(0, (url.indexOf("#") == -1) ? url.length : url.indexOf("#"));
//this removes the query after the file name, if there is one
url = url.substring(0, (url.indexOf("?") == -1) ? url.length : url.indexOf("?"));
//this removes everything before the last slash in the path
url = url.substring(url.lastIndexOf("/") + 1, url.length);
//this removes the file extension
url = url.substring(0, (url.indexOf(".") == -1) ? url.length : url.indexOf("."));
//return
return url
},

/**
* SELECT AN OPTION BY IT'S LABEL
* @param {select field} objThe dropdown to modify
* @return N/A
*/
selectOptByText: function(obj, text) {
if (obj != null) {
text = (text) ? text : $(obj).data('kt_value');
text = text.split(/[\s,-\/]+/);
textfound = '';
for (x = 0; x & lt; text.length; x++) {
textfound = $(obj).find('option:containsi(' + text[x] + ')').first();
if (textfound.length & gt; 0) {
x = text.length;
}
}

if (!KT_Helper.populateFinished & amp; & amp; textfound.length & gt; 0) {
textfound[0].selected = true;
if (obj.disabled) obj.disabled = false;
} else {
obj.options[0].selected = true;
$(obj).change();
}
}
},

/**
* Populate Fields
* @param {String} elemID is the url in which it is located at this time this script
* @return N/A
*/
populateFields: function(kt_data) {
if (typeof kt_data !== null & amp; & amp; typeof kt_data !== 'undefined' & amp; & amp; kt_data !== null & amp; & amp; typeof kt_data.ErrorMessage == 'undefined') {

if (KT_Helper.isLocalStorageAvailable()) {
kt_data_sting = JSON.stringify(kt_data);
localStorage.setItem(KT_ECTOKEN, kt_data_sting);
}
KT_Helper.populateFinished = false;
//KT_Helper.elemID = elemID;
//form = document.getElementById('inquiry');
//elemType = elemID.substr(0,1);
//elemNum = elemID.substr(1,1);

/**
* Filling fields, customized according to your site
* elemenID.indexOf is used to find in which step is located in your site
* @return N/A
*/

//==================================
//==BEGIN: Sections Prefill Fields==
//==================================

console.log("The first Name of Applicant is: " + kt_data.FirstName);
//document.getElementById('lead_form_firstname').value = kt_data.FirstName;
console.log("The Address of Applicant is: " + kt_data.Address1);
//document.getElementById('lead_form_address1').value = kt_data.Address1;

//==================================
//== END: Sections Prefill Fields ==
//==================================

KT_Helper.populateFinished = true;
KT_Helper.prefilledElems[KT_Helper.elemID] = true;
KT_Helper.elemID = '';
}
},

/**
* getCookie
* @param {String} cname, the name of the cookie to be obtained
* @return If the cookie exists, return value and if not return empty
*/
getCookie: function(cname) {
var name = cname + "=";
var ca = document.cookie.split(';');
for (var i = 0; i & lt; ca.length; i++) {
var c = ca[i].trim();
if (c.indexOf(name) == 0) return c.substring(name.length, c.length);
}
return "";
},

/**
* setCookie
* @param {String} cname, the name of the cookie to be defined
* @param {String} cvalue, the value of the cookie to be defined
* @return N/A
*/
setCookie: function(cname, cvalue) {
var d = new Date();
d.setTime(d.getTime() + (12 * 60 * 60 * 1000));
var expires = "expires=" + d.toGMTString();
document.cookie = cname + "=" + cvalue + "; " + expires + ";path=/";;
}
};

var KT_ECTOKEN = KT_Helper.gup('ectoken'),

KT_APIURL = '//ec.katch.com:9044/enhanced/pii/' + KT_ECTOKEN + '?format=json&callback=KT_Helper.populateFields';
JQUERY_URL = '//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js';
JSON_URL = '//cdn.katch.com/p/scripts/json2.js';

if (window.addEventListener) // W3C standard
{
window.addEventListener('load', onLoadFunctions, false);
} else if (window.attachEvent) // Microsoft
{
window.attachEvent('onload', onLoadFunctions);
}

function onLoadFunctions() {

if (!KT_ECTOKEN == false) {
if (KT_Helper.isLocalStorageAvailable()) {
localStorage.setItem('KT_ECTOKEN', KT_ECTOKEN);
}
KT_Helper.setCookie('KT_ECTOKEN', KT_ECTOKEN);
} else {
if (KT_Helper.isLocalStorageAvailable()) {
KT_ECTOKEN = localStorage.getItem('KT_ECTOKEN');
} else {
KT_ECTOKEN = KT_Helper.getCookie('KT_ECTOKEN');
}

}

if (window.jQuery === undefined) {
KT_Helper.include_js(JQUERY_URL);
}

if (window.JSON === undefined) {
KT_Helper.include_js(JSON_URL);
}

if (KT_Helper.isValidKey(KT_ECTOKEN)) {
elemId = KT_Helper.getFileNameURL();
if (KT_Helper.isLocalStorageAvailable()) {
if (typeof localStorage.getItem(KT_ECTOKEN) !== null & amp; & amp; localStorage.getItem(KT_ECTOKEN) !== null & amp; & amp; localStorage.getItem(KT_ECTOKEN) != "null") {
kt_data = JSON.parse(localStorage.getItem(KT_ECTOKEN));
KT_Helper.populateFields(kt_data);
} else {
KT_Helper.include_js(KT_APIURL);
}
} else {
KT_Helper.include_js(KT_APIURL);
}
}
}

Step #4

Testing

You can start testing by using:

&ectoken=3c0cd5ac-0f38-4ee2-9ccc-e0a9ebc65661

Example

https://ec.katch.com:9044/enhanced/pii/3c0cd5ac-0f38-4ee2-9ccc-e0a9ebc65661?format=json