Enhanced Click Implementations

The Katch Search REST API allows you to query listings from our marketplace platform. The API is served over HTTPS.

Since the API is based on REST principles, it’s very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTPS client in any programming language to interact with the API.

Service URL

To use this service you need to do an HTTPS REQUEST (POST type) to this URL:

https://marketplaces.katch.com/enhanced/search

The request Body should contain a structure of data as follows:


{"campaign":"String","state":"String"}
//Sample with Values:
{"campaign": "6604", "state":"CA"}

Example of Request:

https://marketplaces.katch.com/enhanced/search/?state=CA&zipcode=90210&campaign=6604&engagementoption=4&md=4&format=xml

Query String Parameters

Parameters indicated with a “++” are mandatory. This information belongs to the client who is searching in the service consumed and MUST be passed in the query string parameters of the Request:

  • state = Specify state marketplace to use. Valid values are two character state codes. (e.g. state=CA)
  • zipcode = Use this parameter to pass the location of the user making the query. This can only be the zip code in its 5 digit format.(e.g., zipcode=90210)
  • publisherid = This is your Publisher ID, and it will be assigned when you register on Katch’s Platform. Your Publisher ID is (PUBLISHERID)
  • ++ campaign = Campaigns are used to track separate implementations, placements or traffic sources. The Campaign ID for this implementation is (CAMPAIGN)
  • maxresults = Indicates the max number of results intended for the visitor to see. (e.g. “maxResults”: “8“)
  • ++ md = Marketplace definition for your private marketplace that identifies the vertical. The MD for this implementation is (4)
  • engagementoption = This filter will allow you to obtain different types of engagements: clicks, calls or both. When not specified, it will default to clicks. See Table for Reference.
Value Meaning Example of parameter with value
1 Click “engagementoption” : “1”
2 Call “engagementoption” : “2”
4 Click and Call “engagementoption” : “4”
  • ++ client_user_agent = The software agent for an HTTP request, for instance in a browser, will indicate version of the browser, platform (i.e., mobile), etc.
  • client_referrer = The HTTP header that identifies the address of the webpage.
  • client_ip = The IP address that accessed the website.

Filters and Super Bids Parameters

currentlyinsured

Indicates if the user is Currently Insured or not. See Table for Reference.

Value Meaning Example of parameter with value
1 Yes “currentlyinsured” : “1”
2 No “currentlyinsured” : “2”

3yearincidentcount

Incidents in the last 3 years. Tickets/violations, accidents, and claims qualify as an incident. See Table for Reference.

Value Meaning Example of parameter with value
1 0 “3yearincidentcount” : “1”
2 1 “3yearincidentcount” : “2”
3 2 “3yearincidentcount” : “3”
4 3 “3yearincidentcount” : “4”

multidriverhousehold

Indicates if besides the driver, there will be more drivers covered by the policy. See Table for Reference.

Value Meaning Example of parameter with value
1 Yes “multidriverhousehold” : “1”
2 No “multidriverhousehold” : “2”

age

(for multi-driver policy, try to match age of any driver) = Indicates the user’s age. See Table for Reference.

Value Meaning Example of parameter with value
1 <18 “age” : “1”
2 18-24 “age” : “2”
3 25-34 “age” : “3”
4 35-49 “age” : “4”
5 50-64 “age” : “5”
6 65+ “age” : “6”

homeowner

Indicates if the user owns or not his/her place of residence. See Table for Reference.

Value Meaning Example of parameter with value
1 Own “homeowner” : “1”
2 Rent “homeowner” : “2”
3 Other “homeowner” : “3”

yearsofcurrentcoverage*

Indicates the years left of user’s current coverage. See Table for Reference.

Value Meaning Example of parameter with value
1 0 “yearsofcurrentcoverage” : “1”
2 1+ “yearsofcurrentcoverage” : “2”

targetcoverage*

See Table for Reference.

Value Meaning Example of parameter with value
1 Maximum Coverage “targetcoverage” : “1”
2 Better Coverage “targetcoverage” : “2”
3 Good Coverage “targetcoverage” : “3”
4 State Minimum “targetcoverage” : “4”

targetbodilyinjuryliabilitylimits*

See Table for Reference.

Value Meaning Example of parameter with value
1 $10,000/$20,000 “targetbodilyinjuryliabilitylimits” : “1”
2 $15,000/$30,000 “targetbodilyinjuryliabilitylimits” : “2”
3 $25,000/$50,000 “targetbodilyinjuryliabilitylimits” : “3”
4 $30,000/$60,000 “targetbodilyinjuryliabilitylimits” : “4”
5 $50,000/$100,000 “targetbodilyinjuryliabilitylimits” : “5”
6 $100,000/$300,000 “targetbodilyinjuryliabilitylimits” : “6”
7 $250,000/$500,000 “targetbodilyinjuryliabilitylimits” : “7”
8 $500,000/$500,000 “targetbodilyinjuryliabilitylimits” : “8”

Auto Lead Fields

See Lead Fields and Values here.

Publisher Tracking Parameters

There are 5 available parameters for publisher tracking purposes (p1, p2, p3, p4, p5), these can be used to keep track of your traffic sources, unique visitor tracking, or any other value used to track publisher’s traffic. All data sent to these parameters, will be available in our platform reports.

Guidelines for the p1, p2, p3, p4, p5 parameters:

  • Length: 36 characters
  • Allowed characters: Letters, numbers, underscore and dash

Example of usage: (this is just an example)

  • “p1”: “paidtraffic”
  • “p2”: “21EC2020-3AEA-4069-A2DD-08002B30309D”
  • “p3”: “searchengine-123”
  • “p4”: “ty-page”
  • “p5”: “sidebar”

Example of Query String with Parameters and Values

https://marketplaces.katch.com/enhanced/search?state=CA&zipcode=90210&campaign=6604&maxresults=15&md=4&client_user_agent=Mozilla/5.0+(Windows+NT+6.1;+WOW64;+Trident/7.0;+rv:11.0)+like+Gecko&client_referrer=yourdomain.com&client_ip=192.168.5.2&engagementoption=4¤tlyinsured=1&3yearincidentcount=4&multidriverhousehold=2&age=6&homeowner=3&yearsOfcurrentcoverage=2&targetcoverage=4&targetbodilyInjuryliabilitylimits=8&P1=12345678&P2=UPTO32CHARACTERS&format=xml

No Index/No Follow Listings

We strongly recommend to not index the listings by any bot because it may be reflected in your overall traffic quality and penalizations on behalf of our advertisers may be applied. To avoid that, please add the “no follow” to the REL attribute in every listing.

<a href="Advertiser_click_URL" rel="nofollow" target="_blank"></a>

Handling Errors

If there is an error in the request (missing parameters, headers, wrong data in parameters) the XML Structure of Listings will not be returned. Instead, the following error message structure can be returned:

Error output format:

{
"Results": [],
"ResponseStatus": {
"Status": "Error",
"ErrorCode": "{###}",
"Message": "{Error Name}"
}
}

Error Codes and Messages

Error Code Error Name Exception Class
1 Internal Server Error InternalServerErrorException : PerformanceMarketException
2 Invalid Input InvalidInputException : PerformanceMarketException
3 Validation Error ValidationErrorException : PerformanceMarketException

Enhanced Clicks Data

Publishers who wish to implement Enhanced Clicks may see an increase in revenue per visitor, as their media will convert better for Katch advertisers. To include Enhanced Clicks data in the request to the Katch System to receive the XML feed:

Mandatory Parameters:

Value Meaning Example of parameter with value
ecdatatype Indicates the scheme for Enhanced Clicks “ecdatatype” : “Auto2”
ecdata Structure for enhanced clicks information “ecdata” : “{\”driver\”: [{\”FirstName\”:\ “Pamela\”,\”Email\”:\”silverman@gmail.com\”}]}”

The request Body should contain a structure of data as follows:


{"campaign":"String","state":"String", "ecdata":"String","zipcode":"String", "format":"String" }

Sample with Values:


{
"campaign" : "6604",
"state" : "CA",
"publisherid" : "55555",
"zipcode" : "90210",
"md" : "4",
"currentlyinsured" : "2",
"age" : "3",
"yearsofcurrentcoverage" : "2",
"P1" : "123456789",
"ecdata" : "{\"Driver\":[{\"ZipCode\":\"90245\",\"Address1\":\"South Douglas Street\",\"City\":\"El Segundo\",\"State\":\"CA\",\"Phone\":\"(320) 310-1234\",\"Email\":\"ec@katch.com\",\"HomeOwnership\":\"1\",\"CurrentAddressLength\":\"36\",\"CurrentlyInsured\":\"0\",\"CurrentCustomer\":\"0\",\"ContinuousCoverage\":\"0\",\"CoverageType\":\"1\",\"FirstName\":\"Katch\",\"LastName\":\"Demo\",\"Gender\":\"1\",\"Birthday\":\"01/01/1985\",\"MaritalStatus\":\"0\",\"Education\":\"4\",\"PrimaryVehicle\":\"v1\",\"CreditRating\":\"2\",\"Occupation\":\"33\",\"LicenseStatus\":\"0\",\"FilingStatus\":\"0\",\"FirstLicensed\":\"16\",\"Relationship\":\"0\"}],\"Vehicle\":[{\"Year\":\"2014\",\"Make\":\"26\",\"Model\":\"1913\",\"SubModel\":\"PICKUP 2 DOOR\",\"VIN\":\"1FTMF1EFCEF\",\"AlarmSystem\":\"1\",\"PrimaryPurpose\":\"0\",\"OvernightParking\":\"5\",\"AnnualMileage\":\"12500\",\"Ownership\":\"2\"}]}",
"ecdatatype" : "Auto2",
"format":"xml"
}

Example of POST:


Header:
Content-Type: application/jsonBody:{
"campaign" : "6604",
"state" : "CA",
"publisherid" : "55555",
"zipcode" : "90210",
"md" : "4",
"currentlyinsured" : "2",
"age" : "3",
"yearsofcurrentcoverage" : "2",
"P1" : "123456789",
"ecdata" : "{\"Driver\":[{\"ZipCode\":\"90245\",\"Address1\":\"South Douglas Street\",\"City\":\"El Segundo\",\"State\":\"CA\",\"Phone\":\"(320) 310-1234\",\"Email\":\"ec@katch.com\",\"HomeOwnership\":\"1\",\"CurrentAddressLength\":\"36\",\"CurrentlyInsured\":\"0\",\"CurrentCustomer\":\"0\",\"ContinuousCoverage\":\"0\",\"CoverageType\":\"1\",\"FirstName\":\"Katch\",\"LastName\":\"Demo\",\"Gender\":\"1\",\"Birthday\":\"01/01/1985\",\"MaritalStatus\":\"0\",\"Education\":\"4\",\"PrimaryVehicle\":\"v1\",\"CreditRating\":\"2\",\"Occupation\":\"33\",\"LicenseStatus\":\"0\",\"FilingStatus\":\"0\",\"FirstLicensed\":\"16\",\"Relationship\":\"0\"}],\"Vehicle\":[{\"Year\":\"2014\",\"Make\":\"26\",\"Model\":\"1913\",\"SubModel\":\"PICKUP 2 DOOR\",\"VIN\":\"1FTMF1EFCEF\",\"AlarmSystem\":\"1\",\"PrimaryPurpose\":\"0\",\"OvernightParking\":\"5\",\"AnnualMileage\":\"12500\",\"Ownership\":\"2\"}]}",
"ecdatatype" : "Auto2",
"format" : "xml"
}

Example of RESPONSE:


<?xml version="1.0" encoding="UTF-8"?>
<ListingsResult xmlns="http://schemas.datacontract.org/2004/07/Public.Commons.AbstractProtocol.EduSearch.Response" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<OpenMatchListings />
<ResponseStatus>
<Status xmlns="">Ok</Status>
</ResponseStatus>
<Results>
<OutPutListing xmlns="">
<BrandName>Progressive</BrandName>
<Description>
<Element>Paying too much on auto insurance? drivers who switch to Progressive save an average of over $548. So get a free quote today to see how much you could save!</Element>
</Description>
<DescriptionType>Paragraph</DescriptionType>
<DisplayUrl>www.Progressive.com</DisplayUrl>
<EngagementId>f37c84a4-ac9d-4a60-a2f1-b63e3269c6c0_44143</EngagementId>
<HeadLine>Goltry, Oklahoma drivers, you could save hundreds on car insurance with Progressive</HeadLine>
<ListingId>44143</ListingId>
<LogoUrl>//cdn.katch.com/logos/adv_34001.gif?e=f37c84a4-ac9d-4a60-a2f1-b63e3269c6c0_44143&pos=1</LogoUrl>
<Products>
<Product>
<ActionUrl>//marketplaces.katch.com/click/f37c84a4-ac9d-4a60-a2f1-b63e3269c6c0/44143/aHR0cDovL2FkLmRvdWJsZWNsaWNrLm5ldC9jbGs7MjUwMjkwMzc3Ozc1MTY0NTIyO2c7cGM9W1RQQVNfSURdP2h0dHA6Ly93d3cucHJvZ3Jlc3NpdmUuY29tL2xwL2F1dG8tY29tcGFyZS8_Y29kZT04MDE0NTAwMDA0JnppcGNvZGU9NzM3MzkmQldfU1JDPXtlbmdhZ2VtZW50aWR9JmJ3aW5zdXJlZD0mcGhvbmU9ODAxNDUmYWR2X2VjdG9rZW49e2VjdG9rZW59Jm1pZD0xMDA5</ActionUrl>
<Type>Click</Type>
</Product>
</Products>
</OutPutListing>
<OutPutListing xmlns="">
<BrandName>Esurance</BrandName>
<Description>
<Element>Oklahoma drivers - See If You Can Save Today - Get a Quote.</Element>
<Element>You Could Qualify for One or More of Our Big Discounts.</Element>
<Element>We've Insured Over 5 million Vehicles Since 1999.</Element>
<Element>24/7 Customer Service - Located in the USA.</Element>
</Description>
<DescriptionType>Bulleted</DescriptionType>
<DisplayUrl>www.esurance.com/Oklahoma</DisplayUrl>
<EngagementId>f37c84a4-ac9d-4a60-a2f1-b63e3269c6c0_43372</EngagementId>
<HeadLine>You Could Save with Esurance!</HeadLine>
<ListingId>43372</ListingId>
<LogoUrl>//cdn.katch.com/logos/adv_34003.gif?e=f37c84a4-ac9d-4a60-a2f1-b63e3269c6c0_43372&pos=2</LogoUrl>
<Products>
<Product>
<ActionUrl>//marketplaces.katch.com/click/f37c84a4-ac9d-4a60-a2f1-b63e3269c6c0/43372/aHR0cDovL3d3dy5lc3VyYW5jZS5jb20_dHM9MTMmcHJvbW9pZD1CS1dBRl9PS18wMDAyJnBhcnRuZXJfY2Q9e3NvdXJjZV9pZH0tY2FtcGFpZ24te3NvdXJjZV9zdWJpZH0tcHJpb3ItLWFnZS0taW5jaWRlbnQtLW11bHRpLS1ob21lLS1jbGlja2lkLXtlbmdhZ2VtZW50aWR9LWNyZWF0aXZlLWImemlwY29kZT03MzczOSZhZHZfZWN0b2tlbj17ZWN0b2tlbn0mbWlkPTEwMDc.</ActionUrl>
<Type>Click</Type>
</Product>
</Products>
</OutPutListing>
</Results>
</ListingsResult>

Test and Development

At the time of testing, please always set the parameter “testtransaction” : “true”


Header:
Content-Type: application/jsonBody:
{
"campaign" : "6604",
"state" : "CA",
"publisherid" : "55555",
"zipcode" : "90210",
"md" : "4",
"currentlyinsured" : "2",
"age" : "3",
"yearsofcurrentcoverage" : "2",
"P1" : "123456789",
"ecdata" : "{\"Driver\":[{\"ZipCode\":\"90245\",\"Address1\":\"South Douglas Street\",\"City\":\"El Segundo\",\"State\":\"CA\",\"Phone\":\"(320) 310-1234\",\"Email\":\"ec@katch.com\",\"HomeOwnership\":\"1\",\"CurrentAddressLength\":\"36\",\"CurrentlyInsured\":\"0\",\"CurrentCustomer\":\"0\",\"ContinuousCoverage\":\"0\",\"CoverageType\":\"1\",\"FirstName\":\"Katch\",\"LastName\":\"Demo\",\"Gender\":\"1\",\"Birthday\":\"01/01/1985\",\"MaritalStatus\":\"0\",\"Education\":\"4\",\"PrimaryVehicle\":\"v1\",\"CreditRating\":\"2\",\"Occupation\":\"33\",\"LicenseStatus\":\"0\",\"FilingStatus\":\"0\",\"FirstLicensed\":\"16\",\"Relationship\":\"0\"}],\"Vehicle\":[{\"Year\":\"2014\",\"Make\":\"26\",\"Model\":\"1913\",\"SubModel\":\"PICKUP 2 DOOR\",\"VIN\":\"1FTMF1EFCEF\",\"AlarmSystem\":\"1\",\"PrimaryPurpose\":\"0\",\"OvernightParking\":\"5\",\"AnnualMileage\":\"12500\",\"Ownership\":\"2\"}]}",
"ecdatatype" : "Auto2",
"format" : "xml"
"testtransaction" : "true"
}

Support

If you have any trouble setting this up, please contact us at implementations-support@katch.com.