Regular Implementations

Implementing Medicare Insurance XML Listings

Overview

The Katch Search REST API allows you to query listings from our marketplace platform. The API is served over both HTTP and 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 HTTP client in any programming language to interact with the API.

Service URL

To use this service you need to make an HTTP POST REQUEST to the following URL:

http://marketplaces.katch.com/Search

You need to send a JSON Request Body as follows:

{"campaign": string,"md": string,"state":string}

Example of request:


POST http://marketplaces.katch.com/Search
Accept: application/xml
Content-Type: application/json
Request Body: {"campaign": "6604","md":"10","state":"CA"}
 

Parameters Description

(Parameters indicated with a “++” are mandatory)

  • ++md = Marketplace definition identifier. The MD for this implementation is (10)
  • ++state = Specific state marketplace to query. Value needs be sent in state code format. (example -> state = CA)
  • ++campaign = Campaigns are used to track separate implementations, placements or traffic sources. The Campaign ID for this implementation is (xxxxx)
  • 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)
  • maxresults = Indicates the max number of results intended for the visitor to see. (e.g. “maxResults”: “8”)
  • engagementoption = This filter will allow you to obtain different types of engagements: clicks, calls or both. When not specified, it will default to clicks only. 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 making the request.
  • client_referrer: This header field allows the client to specify, the address ( URI ) from which the the request was made.
  • 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”

Example of query String with parameters and values

http://marketplaces.katch.com/search?state=CA&zipcode=90210&campaign=6604&maxresults=15&md=10&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=paidtraffic&p2=21EC2020-3AEA-4069-A2DD-08002B30309D&p3=searchengine-123&p4=ty-page&p5=sidebar&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 add “no follow” to the REL attribute in every listing.

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

Results Output


<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="">
<Description>
<Element>From $10,000 to $100,000 in affordable coverage for ages 50-74></Element>
<Element>No medical exam - acceptance is based on answers to a few health questions and other information we collect></Element>
<Element>No waiting period</Element>
<Element>Group coverage exclusively for AARP members. If you're not a member it's easy to join - we'll send you everything you need></Element>
</Description>
<DescriptionType>Bulleted <DisplayUrl>www.nylaarp.com <EngagementId>c4084e5d-d01d-497f-9d16-9145b3020f11_282929></EngagementId>
<ExtraAttributes />
<HeadLine>AARP Life Insurance Program from New York Life Insurance Company.></HeadLine>
<ListingId>282929 <LogoUrl>//cdn.katch.com/logos/77857.gif?e=7ce1efe5-0cc5-433a-80f2-17d4f3b919ec_106507&pos=3&e=c4084e5d-d01d-497f-9d16-9145b3020f11_282929&pos=1></LogoUrl>
<Products>
<Product>
<ActionUrl>//marketplaces.katch.com/click/c4084e5d-d01d-497f-9d16-9145b3020f11/282929?t=Ly9tYXJrZXRwbGFjZXMua2F0Y2guY29tL2NsaWNrLzdjZTFlZmU1LTBjYzUtNDMzYS04MGYyLTE3ZDRmM2I5MTllYy8xMDY1MDcvYUhSMGNEb3ZMM2QzZHk1dWVXeGhZWEp3TG1OdmJTOWljbTlyWlhKemQyVmlMekl3TVRVdk1UUV9jMjkxY21ObFBYdHpiM1Z5WTJWZmFXUjk.></ActionUrl>
<Type>Click></Type>
</Product>
</Products>
</OutPutListing>
</Results>
</ListingsResult>
 

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:


<?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 i:nil="true" />
<ResponseStatus>
<ErrorCode xmlns="">1</ErrorCode>
<Message xmlns="">Invalid Marketplace Definition Id</Message>
<Status xmlns="">Error</Status>
</ResponseStatus>
<Results />
</ListingsResult>
 

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.