HIP Manager Open Point API

	Contact Us
	Resources
	Affiliation

Home - Help - HIP Manager Open Point API

HIP Manager Open Point API

1. Overview
2. Prerequisites
3. Authentication Mechanism
4. Retrieving a retail price for a new order
5. Posting a new HIP Quotation
6. Retrieving a Progress Bar for Processing Orders
7. Setting up your own Listener API

Appendix A
Appendix B
Appendix C

1. Overview

The HIP Manager API is an extension of the White Label system that enables certain functions to be performed over a remote Web Service. Currently the API supports the following functions.

Retrieve the price for a given order

Post a new HIP quotation

Retrieve an order progress indicator

As the API evolves additional functions will become available.

2. Prerequisites

To access the API functions you must have a HIP Manager Account with the White Label module enabled. Communication with the web service is made via the Simple Object Access Protocol (SOAP) Standard with the data encapsulated into XML feeds.

All the methods available through the API can be previewed from here:
http://www.hipmanager.com/webServices/wlAPI/openPoint.asmx

3. Authentication Mechanism

The API uses a simple authentication mechanism to validate each request. Each post will require the following information:

Registered Email
The email address registered to your HIP Manager Account.

MD5 Encrypted Password
An MD5 encrypted hash of the account password

Test Mode Indicator
0 for Live submissions. 100 for test submissions.

The following online tool can be used to MD5 encrypt your password:
http://www.logicalpackets.com/md5.asp

4. Retrieving a Retail Price for a New Order

The API has a function that returns a numeric value corresponding to the VAT inclusive (where applicable) order total for a given collection of components. The function requires the account number and the order token to calculate and return the retail price for the quotation.

Please refer to Appendix A for information on the order token.

The purpose of this function is to enable any price changes made on the HIP Manager control panel to seamlessly affect the prices quoted within your own application.

Web Service Method: getRetailPrice

An instance of the getRetailPrice method can be created when the web service is referenced from within your application.

4.1 Data Schema for getRetailPrice

Property	Description	Mandatory	Type	Permissible Values
accNumber	Valid HIP Manager Account Number	Y	String (Max 20 Chars)	Valid HIP Manager Account Number
subAccID	Sub Account Number	Y	String (Max 20 Chars)	A valid sub account associated with the master account
authEmail	Registered account email	Y	String	The registered login email associated with the supplied account number
authPassword	MD5 Hash of the account password	Y	String	MD5 encrypted password associated with the supplied account number
orderStr	Token to determine which components of the HIP are to be quoted for	Y	String	See Appendix A

4.2 getRetailPrice Response

The getRetailPrice method returns an XML response containing the calculated retail price configured on the account in pounds and pence. If the request is invalid the method will return a single or multiple error definitions as per Appendix B.

Please refer to the sample request and response

Posting a new HIP Quotation

Before a new HIP quotation can be submitted to the API the following information must be collecting by your user interface.

1. Address for which the HIP will be compiled
2. The tenure of the property (Freehold, Leasehold or Commonhold)
3. Number of bedrooms
4. Property Description
5. Client Email address
6. Client contact telephone number

The above information is wrapped up into an xml document and submitted to the API. The data is checked against a schema and if the request is valid the API returns a URL so that the client can be redirected to the payment options screen.

Web Service Method: postQuotation

An instance of the postQuotation method can be created when the web service is referenced from within your application.

5.1 Data Schema for postQuotation

Property	Description	Mandatory	Type	Permissible Values
accNumber	Valid HIP Manager Account Number	Y	String (Max 20 Chars)	Valid HIP Manager Account Number
subAccID	Sub Account Number	Y	String (Max 20 Chars)	A valid sub account associated with the master account
authEmail	Registered account email	Y	String	The registered login email associated with the supplied account number
authPassword	MD5 Hash of the account password	Y	String	MD5 encrypted password associated with the supplied account number
testMode	Determines if the request is TEST or LIVE	Y	varchar(3)	Use 0 for live submissions and 100 for test
clientReference	Clients reference to acknowledge the user	N	varchar(40)	Optional client reference to identify the user
hipReference	Reference for this order. Usually the first line of the address.	Y	varchar(80)	Quote reference (e.g. partial address of customer name)
add1	House Number/Name for which the HIP will be compiled	Y	varchar(100)	House name/number
add2	Street name for which the HIP will be compiled	Y	varchar(100)	Street Name
add3	Locality for which the HIP will be compiled	N	varchar(100)	Locality
town	Town for which the HIP will be compiled	Y	varchar(50)	Town
county	County for which the HIP will be compiled	Y	varchar(50)	County
postcode	Postcode for which the HIP will be compiled	Y	varchar(20)	Postcode
tenureID	ID to determine the tenure of the property	Y	varchar(2)	01 = Freehold, 02 = Commonhold, 03 = Leasehold
propertyType	A description of the property build type	Y	varchar(40)	See Appendix C
bedrooms	Number of bedrooms at the address	Y	Integer	Number of bedrooms 1 - 15
orderStr	Token to determine which components of the HIP are to be quoted for	Y	varchar(10)	See Appendix A
retailPrice	The numeric value of the retail price including VAT where applicable	Y	Double	Exclude additional formatting e.g. currency symbol
clientEmail	The email that will be used to communicate with the client	Y	varchar(100)	Valid email address
clientTel	The telephone number that will be used to communicate with the client	Y	varchar(50)	valid telephone number
ipAddress	The users IP address	Y	varchar(15)	Valid IP Address e.g. 127.0.0.1

5.2 postQuotation Response

The postQuotation function returns an xml response. If the request is successful the response will contain an encoded URL that must be used to redirect the customer to the payment screen. If testMode is set to 100 then the API returns a SUCCESS message. If the request does not comply with our validation schema the function will return a collection of error codes (please see Appendix B). Each error code will have a description of the precise problem.

Please refer to the sample request and response for this function

6. Retrieving a Progress Bar for Processing Orders

This function enables a string to be returned that indicates the extent to which a processing HIP order has been completed along with the overall order status.

For example:

Consider the order token ABCEF. This represents a typical Leasehold HIP order. If the Title documents and Local Authority Search are complete with the Drainage and Water Search, Energy Performance Certificate and leasehold documents pending the response from this function would render two shaded blocks and three unshaded blocks.

6.1 Web Service Method: getProgressIndicator

An instance of the getProgressIndicator method can be created when the web service is referenced from within your application.

Property	Description	Mandatory	Type	Permissible Values
accNumber	Valid HIP Manager Account Number	Y	String (Max 20 Chars)	Valid HIP Manager Account Number
subAccID	Sub Account Number	Y	String (Max 20 Chars)	A valid sub account associated with the master account
authEmail	Registered account email	Y	String	The registered login email associated with the supplied account number
authPassword	MD5 Hash of the account password	Y	String	MD5 encrypted password associated with the supplied account number
trackerID	Unique ID representing the order on our database	Y	integer	1 - 1000000000

6.2 getProgressIndicator Response

The response for this method includes a progress string defined as follows:

[number of completed components] | [total number of components ordered]

For example: 3|5
Means: 3 of 5 components have been completed on the HIP.

This method also returns a value to show the overall status of the order. The value may be any of the following:

PENDING	The order is currently being processed by our admin department
PARKED	The order is awaiting a client response. Often indicating a requirement to obtain futher information before the order can be progressed.
COMPLETE	All components have been ordered and the HIP has been compiled and made available to the client.
CANCELLED	The order has been cancelled.

Please refer to the sample request and response examples

7. Setting up your own Listener API

Many of the functions available on this web service will require two way communication with your server. For example once a quotation has been provided and the client remits payment for the order the API must have some way of providing information on the order to update your application and facilitate further calls.

The basis of all orders stored on our system is the tracker ID. This is an integer value that can be used to make subsequent calls for information on the order progress, available documents, messages, notes and general activity associated with an order.

7.1. New Tracker Notification

A tracker ID is created by our admin department before any work is carried out on an order. We will notify you whenever a tracker has been created by making a call to your listener service.

In order for this communication to work you must setup a simple web service with the function 'newTrackerNotification'. The function should accept just one string variable that will act as a container for the XML.

When you have setup this web service you can test the communication by using the following tool:

Open Point New Tracker Notification Validator

You must then inform us of the URL where your web service resides along with the username and password that we need to use for validation. If necessary your web service can also use SSL encryption for added security.

7.2 Example XML Request

The following link will show an example XML Request made to your web service. The request will contain your client reference, tracker ID and the associated address details lodged on our system. The XML will also carry your preagreed username and password to enable you to authenticate the request.

Example of the newTrackerNotification

7.3 Listener Response

Our system will expect a string response that will indicate whether or not the request was successful. The table below illustrates the permissible values returned from your web service.

0	Transmission was Successful
01	Internal Server Error
02	Authentication Failed

Appendix A

Order Token (orderStr)

The order token is a string of characters that are used to determine the component parts of the Home Information Pack.

Character	Component
A	Local Authority Search
B	Drainage and Water Search (Con29DW)
C	HMLR Title documents
D	Printed copy of the HIP
E	Energy Performance Certificate
F	Leasehold documentation (Mandatory for leasehold properties)
G	Commonhold documentation (Mandatory for commonhold properties)

The items highlighted are statutory parts of the Home Information Pack and must be included if the customer requires a complete HIP. Please note that if the property is leasehold or commonhold characters F and G must be included respectively.

ABCE: Complete Freehold HIP Example
ABCEF: Complete Leasehold HIP Example:
ABCEG: Complete Commonhold HIP Example

The API will assume all requests are being made for complete HIPs. If partial orders are being submitted the agent must obtain prior consent.

Appendix B

The API uses a common error reporting tool to assist in debugging your application.

Error Code Descriptions

Error Code	Description
00	Authentication Failed
01	subAccID is incorrect length
02	Missing or invalid testMode. Supply 0 for LIVE or 100 for TEST
03	hipReference is incorrect length
04	add1 is incorrect length
05	add2 is incorrect length
06	add3 exceeds prescribed length of 100 characters
07	town is incorrect length
08	county is incorrect length
09	postcode is incorrect length
10	Unrecognised tenureID
11	Invalid number of bedrooms
12	Unrecognised property type
13	Invalid orderStr tag
14	Title documents must be ordered with a Local Authority Search
15	Title documents must be ordered with a Drainage and Water Search
16	Title documents cannot be ordered exlusively
17	Commonhold documentation must be ordered if the tenure is declared as commonhold
18	Leasehold documentation must be ordered if the tenure is declared as leasehold
19	The users IP address is missing or invalid
20	The retail price provided does not match the price expected on this account. Please use getRetailPrice function to verify.
21	Invalid Tracker ID. No match on tracker for this account.
22	Client email address is missing or invalid. Maximum Length is 100.
23	Client contact number is missing

Appendix C

The following is a list of permissible property descriptions submit through the propertyType value:

SEMI_DETACHED_HOUSE
DETACHED_HOUSE
TERRACED_HOUSE
APARTMENT
BARN_CONVERSION
BUNGALOW
COTTAGE
STUDIO
LINK_DETACHED_HOUSE
MAISONETTE
MEWS_HOUSE
MOBILE_HOME
CHALET_STYLE
OTHER

Home Information Packs - Sample HIP - Open an Account - FAQ - Contact us