Regular Implementations

Implementing Mortgage 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=3&loantype=1format=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 (3)
  • ++loantype= Used to specify the type of loan needed. It will define if the Marketplace will be Purchase, Refinance or Poor. See Table for Reference.
Value Meaning Example of parameter with value
1 Purchase “loantype” : “1”
2 Refinance “loantype” : “2”
3 Poor “loantype” : “3”
  • 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

loantype

Used to specify the type of loan needed. It will define if the Marketplace will be Purchase, Refinance or Poor (if the creditscore is 4 or 5). See Table for Reference.

Value Meaning Example of parameter with value
1 Purchase “loantype” : “1”
2 Refinance “loantype” : “2”

creditscore

Determines the user’s credit score. See Table for Reference.

Value Meaning Example of parameter with value
1 Excellent “creditscore” : “1”
2 Very Good “creditscore” : “2”
3 Good “creditscore” : “3”
4 Fair “creditscore” : “4”
5 Poor “creditscore” : “5”

propertytype

Indicates the type of property to which the user is interested in. See Table for Reference.

Value Meaning Example of parameter with value
1 Single Family “propertytype” : “1”
2 Condo/Townhome “propertytype” : “2”
3 Multi-Unit “propertytype” : “3”
4 Mobile “propertytype” : “4”

propertyuse

Defines the primary use of the property. See Table for Reference.

Value Meaning Example of parameter with value
1 Primary Residence “propertyuse” : “1”
2 Vacation Home “propertyuse” : “2”
3 Investment “propertyuse” : “3”

Super Bids Parameters

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=3&loantype=1&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.