Auto Tier II

Implementing Auto Tier II Insurance XML Listings

Overview

This is a Restful Web service created with the XML implementation, this web service allows to the get listings from the Katch System and be consumed in XML format. This implementation restricts the pass of parameters in the URL query string. There is no limit on the number of parameters.

Service URL

To use this service you need to do a HTTP REQUEST (POST type) to this URL:

http://marketplaces.katch.com/Search

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


{"campaign":"String","zipcode":"String"}
//Sample with Values:
{"campaign":"22799","zipcode":"90210"}

Example of request:

http://marketplaces.katch.com/Search?state=CA&zipcode=90210&campaign=22799&engagementoption=4&md=7&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 (xxxxx)
  • ++campaign = Campaigns are used to track separate implementations, placements or traffic sources. The Campaign ID for this implementation is (xxxxx)
  • maxresults = Indicates the max number of results intended for the visitor to see.
  • ++md = Marketplace definition for your private marketplace that identifies the vertical. The MD for this implementation is (7)
  • 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.
  • 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”

    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”

    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 add “no follow” to the REL attribute in every listing.

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

    Example of query String with parameters and values

    http://marketplaces.katch.com/Search?state=CA&zipcode=90210&campaign=6604&maxresults=15&md=7&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&P1=12345678&P2=UPTO32CHARACTERS&format=xml

    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 InternalServerErrorExcpetion : PerformanceMarketException
    2 Invalid Input InvalidInputException : PerformanceMarketException
    3 Validation Error ValidationErrorException : PerformanceMarketException

    For Support:

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