Page Comparison

IntroductionRepresentational State Transfer (Wikipedia

SOAP (abbreviation for Simple Object Access Protocol) is a series of endpoints that allow access to stateless representations of data objects (e.g. properties, contacts, tenancies, etc) using standard HTTP requests.The Reapit REST messaging protocol specification for exchanging structured information in the implementation of web services in computer networks. Its purpose is to provide extensibility, neutrality and independence. Wikipedia

The Reapit SOAP API allows 3rd parties access to create, read and update Reapit clients' data via a set of defined endpointsmethods.

An API endpointA WSDL URL, e.g. https://webservice.reapit.net/demo/rest/?wsdl
A Client ID, e.g. DemoUser
An API keyPassword, e.g. 8ed799bbe77c96311e71f64b99ec2ddde765d13a
A client. This can be something as simple as a browserthe Reapit Web Service Test Tool, a library or, on the command line, curl. (e.g. PHP’s SoapClient class, or Node.JS' Soap library), a client app (e.g. SoapUI) or, on the command line, curl. For testing and troubleshooting we recommend using Postman. How to use Postman.

Authorisation

Authorisation is handled by an API key that determines whether or not the REST client has access to the API but also the methods it has access to.

The key should be supplied in the header of each request thus:

Code Block
ApiKey: [ ApiKey ]

e.g.

Code Block
ApiKey: 8ed799bbe77c96311e71f64b99ec2ddde765d13a

If you’re using Postman to test the API, you can set the authorisation at Collection or Request level.

Expand

title	Setting Postman authorisation at Collection level:

Image Removed

Expand

title	Setting authorisation at Request level:

Image Removed

Retrieving Properties

Info

A note about Reapit departments

Each property in a client’s system belongs to a single ‘department’. Each client's departments may be set up differently and can be any of (but not limited to): ‘General', 'Sales', 'Lettings', 'Commercial', 'Agricultural'. The most common department for residential sales and lettings is 'General’.

Because of this, the Reapit APIs' Property methods are all sub-divided by department. In the example web service used here, there is one department: 'General' and this is reflected in the property retrieval method exposed by the API: GET /properties/general

Please note that if a department is called 'Sales' or 'Lettings', its search methods won't necessarily return properties that are for sale or to let. The SearchType parameter should be invoked to control this instead.

Endpoint

Properties are retrieved using the endpoint GET /properties/{ department } e.g.

Code Block
GET https://webservice.reapit.net/demo/rest/properties/general

Expand

title	GET /properties/general/ - Postman example:

Image Removed

If no other parameters are provided, a list of currently live properties will be returned containing only the property ID.

Specifying Fields

To request specific fields in the response, the PropertyField parameter can be supplied with a comma separated list of required fields:

Code Block
GET https://webservice.reapit.net/demo/rest/properties/general?PropertyField=ID,Address1,Postcode,Price

Expand

title	Specifying fields - Postman example

Image Removed

Lettings Properties

By default, GET /properties/{ department } returns properties for sale by the specified department. To retrieve lettings properties, set the SearchType parameter to ‘lettings’

Code Block
GET https://webservice.reapit.net/demo/rest/properties/general?SearchType=Lettings

Expand

title	Lettings properties - Postman example

Image Removed

Filtering results

The REST API offers a large number of options by which to filter the properties returned, including price, attributes, status and location. For a full list of available options, please search for ‘GeneralSearchCriteria’ on this page.

To filter results, supply the criteria as parameters:

Code Block
GET https://webservice.reapit.net/demo/rest/properties/general?MaxPrice=500000&MinBeds=3

Expand

title	Filtering results - Postman example.

Image Removed

If large amounts of data are being requested (e.g. many fields and/or large numbers of properties), it’s best to paginate the results to retrieve the results in chunks. This is achieved with the Offset and Limit parameters:

Code Block
GET https://webservice.reapit.net/demo/rest/properties/general?Offset=50&Limit=50

Expand

title	Pagination - Postman example

Image Removed

Retrieving a Single Property

Single properties are retrieved using the GET /properties/{id} endpoint. E.g.

Code Block
GET https://webservice.reapit.net/demo/rest/properties/rps_zzm-BUC150053

By default, all available property fields will be returned but these can be controlled by supplying the Fields parameter, e.g:

Code Block
GET https://webservice.reapit.net/demo/rest/properties/rps_zzm-BUC150053?Fields=ID,PriceString,Postcode

Expand

title	Retrieving a single property. Postman example.

Image Removed

Getting an Unavailable Property

If a property is marked unavailable (e.g. ‘No internet advertising’ is ticked in the RPS software), its data can still be retrieved by supplying the GetUnavailable parameter as true.

...

the Web Service Test Tool.

WSDL

The starting point for a SOAP API is its WSDL (Web Service Description Language) document, which describes all the methods and datatypes handled by the API. It is an XML document and, whilst readable by a human, is generally consumed by a SOAP client in order to aid interaction between to programming interfaces.

The SOAP Request

SOAP works by posting an XML document containing all the data relating to the request in the HTTP request body to a specific endpoint. When troubleshooting SOAP problems it is often useful to inspect the Request body to see what is being sent to the API, to determine whether a problem exists at the client end, or the API end. An example request document is below:

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://webservice.reapit.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://soapinterop.org/echoheader/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Header>
		<ns2:ClientID>DemoUser</ns2:ClientID>
		<ns2:Password>8ed799bbe77c96311e71f64b99ec2ddde765d13a</ns2:Password>
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		<ns1:GetGeneralProperty>
			<ID xsi:type="xsd:string">rps_demo-RPT200123</ID>
		</ns1:GetGeneralProperty>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The document is made up of two sections, the header, which contains authorisation data, and the body, which contains request data. In the example above, the request is to the GetGeneralProperty method and with the supplied ID parameter.

Authorisation

Authorisation is handled with a Client ID and password, passed in the header of the Soap Request document as ClientID and Password, respectively.

The data should be supplied in the header of each request thus:

Code Block
<SOAP-ENV:Header> <ns2:ClientID>[ ClientID ]</ns2:ClientID> <ns2:Password>[ Password ]</ns2:Password> </SOAP-ENV:Header>

e.g.

Code Block
<SOAP-ENV:Header> <ns2:ClientID>DemoUser</ns2:ClientID> <ns2:Password>8ed799bbe77c96311e71f64b99ec2ddde765d13a</ns2:Password> </SOAP-ENV:Header>

If you’re using the Web Service Test Tool to test the API, you set these values on the first page and click Load:

Expand

title	Setting ClientID and Password using the Web Service Test Tool:

Image Added

The methods you can access will be determined by the permissions granted to the API Key you’re using and will be listed down the left hand side of the following page:

...

Retrieving Properties

Info

A note about Reapit departments

Each property in a client’s system belongs to a single ‘department’. Each client's departments may be set up differently and can be any of (but not limited to): ‘General', 'Sales', 'Lettings', 'Commercial', 'Agricultural'. The most common department for residential sales and lettings is 'General’.

Because of this, the Reapit APIs' Property methods are all sub-divided by department. In the example web service used here, there is one department: 'General' and this is reflected in the property retrieval method exposed by the API: GetGeneralProperties

Please note that if a department is called 'Sales' or 'Lettings', its search methods won't necessarily return properties that are for sale or to let. The SearchType parameter should be invoked to control this instead.

Method

Properties are retrieved using the method GetGeneralProperties.

Criteria used to filter the required properties can be supplied in the Request body.

Expand

title	Sample SOAP Request showing search criteria

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://webservice.reapit.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://soapinterop.org/echoheader/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Header>
		<ns2:ClientID>DemoUser</ns2:ClientID>
		<ns2:Password>8ed799bbe77c96311e71f64b99ec2ddde765d13a</ns2:Password>
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		<ns1:GetGeneralProperties>
			<Criteria xsi:type="ns1:GeneralSearchCriteria">
				<SearchType xsi:type="ns1:SearchType">sales</SearchType>
				<MinPrice xsi:type="xsd:int">300000</MinPrice>
				<MaxPrice xsi:type="xsd:int">400000</MaxPrice>
				<MinBeds xsi:type="xsd:int">4</MinBeds>
			</Criteria>
		</ns1:GetGeneralProperties>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

A full list of search options is available in the Web Service Test Tool.

Response

The SOAP API returns an XML document containing the requested data. In this case, just the ID attributes of the properties that match the criteria.

Expand

title	Sample response from GetGeneralProperties

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://webservice.reapit.com/">
	<SOAP-ENV:Body>
		<ns1:GetGeneralPropertiesResponse xmlns:ns1="http://webservice.reapit.com/">
			<Properties xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="tns:GeneralProperty[3]">
				<item xsi:type="tns:GeneralProperty">
					<ID xsi:type="xsd:string">rps_zzm-BED150463</ID>
				</item>
				<item xsi:type="tns:GeneralProperty">
					<ID xsi:type="xsd:string">rps_zzm-MKC160012</ID>
				</item>
				<item xsi:type="tns:GeneralProperty">
					<ID xsi:type="xsd:string">rps_zzm-NEP140310</ID>
				</item>
			</Properties>
		</ns1:GetGeneralPropertiesResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Specifying Fields

To request specific fields in the response, the PropertyField parameter can be supplied as an array of required fields. Using the Web Service Test Tool, these can be ticked in the PropertyField section, towards the bottom of the GetGeneralProperty page:

...

This generates the following SOAP Request:

Expand

title	SOAP Request with required property fields.

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://webservice.reapit.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://soapinterop.org/echoheader/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Header>
		<ns2:ClientID>DemoUser</ns2:ClientID>
		<ns2:Password>8ed799bbe77c96311e71f64b99ec2ddde765d13a</ns2:Password>
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		<ns1:GetGeneralProperties>
			<Criteria xsi:type="ns1:GeneralSearchCriteria">
				<SearchType xsi:type="ns1:SearchType">sales</SearchType>
				<MinPrice xsi:type="xsd:int">300000</MinPrice>
				<MaxPrice xsi:type="xsd:int">400000</MaxPrice>
				<MinBeds xsi:type="xsd:int">4</MinBeds>
				<PropertyField xsi:type="ns1:GeneralPropertyField">ID</PropertyField>
				<PropertyField xsi:type="ns1:GeneralPropertyField">PriceString</PropertyField>
				<PropertyField xsi:type="ns1:GeneralPropertyField">SaleStatus</PropertyField>
				<PropertyField xsi:type="ns1:GeneralPropertyField">Postcode</PropertyField>
				<PropertyField xsi:type="ns1:GeneralPropertyField">Bedrooms</PropertyField>
			</Criteria>
		</ns1:GetGeneralProperties>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Lettings Properties

By default, Get[ Department ]Properties returns properties for sale by the specified department. To retrieve lettings properties, set the SearchType parameter to ‘lettings’:

...

If large amounts of data are being requested (e.g. many fields and/or large numbers of properties), it’s best to paginate the results to retrieve the results in chunks. This is achieved with the Offset and Limit parameters:

...

Expand

title	SOAP Request with pagination

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://webservice.reapit.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://soapinterop.org/echoheader/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Header>
		<ns2:ClientID>DemoUser</ns2:ClientID>
		<ns2:Password>8ed799bbe77c96311e71f64b99ec2ddde765d13a</ns2:Password>
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		<ns1:GetGeneralProperties>
			<Criteria xsi:type="ns1:GeneralSearchCriteria">
				<SearchType xsi:type="ns1:SearchType">sales</SearchType>
				<PropertyField xsi:type="ns1:GeneralPropertyField">ID</PropertyField>
				<PropertyField xsi:type="ns1:GeneralPropertyField">PriceString</PropertyField>
				<PropertyField xsi:type="ns1:GeneralPropertyField">SaleStatus</PropertyField>
				<PropertyField xsi:type="ns1:GeneralPropertyField">Postcode</PropertyField>
				<PropertyField xsi:type="ns1:GeneralPropertyField">Bedrooms</PropertyField>
				<Offset xsi:type="xsd:int">0</Offset>
				<Limit xsi:type="xsd:int">50</Limit>
			</Criteria>
		</ns1:GetGeneralProperties>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Retrieving a Single Property

Single properties are retrieved using the Get[ Department ]Property endpoint. E.g. GetGeneralProperty.

By default, all available property fields will be returned but these can be controlled by supplying the Fields parameter, e.g:

...

This generates the following SOAP Request:

Expand

title	Retrieving a single property. SOAP Request.

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://webservice.reapit.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://soapinterop.org/echoheader/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Header>
		<ns2:ClientID>DemoUser</ns2:ClientID>
		<ns2:Password>8ed799bbe77c96311e71f64b99ec2ddde765d13a</ns2:Password>
		<ns2:SessionID>oeg5c0arf0701649brkc579qc7</ns2:SessionID>
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		<ns1:GetGeneralProperty>
			<ID xsi:type="xsd:string">rps_zzm-BED150463</ID>
			<FieldList xsi:type="ns1:GeneralPropertyFieldList">
				<Fields xsi:type="ns1:GeneralPropertyField">ID</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">PriceString</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">HouseName</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">HouseNumber</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Address1</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Address2</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Address3</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Address4</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Postcode</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Description</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Image</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">PrintableDetails</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Bedrooms</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Type</Fields>
			</FieldList>
			<GetUnavailable xsi:type="xsd:boolean">false</GetUnavailable>
		</ns1:GetGeneralProperty>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Getting an Unavailable Property

If a property is marked unavailable (e.g. ‘No internet advertising’ is ticked in the RPS software), its data can still be retrieved by supplying the GetUnavailable parameter as true:

...

This will generate the following SOAP Request:

Expand

title	Get unavailable property. SOAP Request.

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://webservice.reapit.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://soapinterop.org/echoheader/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Header>
		<ns2:ClientID>DemoUser</ns2:ClientID>
		<ns2:Password>8ed799bbe77c96311e71f64b99ec2ddde765d13a</ns2:Password>
		<ns2:SessionID>oeg5c0arf0701649brkc579qc7</ns2:SessionID>
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		<ns1:GetGeneralProperty>
			<ID xsi:type="xsd:string">rps_zzm-BED150463</ID>
			<FieldList xsi:type="ns1:GeneralPropertyFieldList">
				<Fields xsi:type="ns1:GeneralPropertyField">ID</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">PriceString</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">HouseName</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">HouseNumber</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Address1</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Address2</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Address3</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Address4</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Postcode</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Description</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Image</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">PrintableDetails</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Bedrooms</Fields>
				<Fields xsi:type="ns1:GeneralPropertyField">Type</Fields>
			</FieldList>
			<GetUnavailable xsi:type="xsd:boolean">true</GetUnavailable>
		</ns1:GetGeneralProperty>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Retrieving Contacts

Contacts are retrieved using the GET /contacts endpoint. E.g:

...

Code Block

language	json

{
  "Title": "Mrs",
  "Initials": "Lisa",
  "Surname": "Jones",
  "HouseNumber": "12a",
  "Address1": "High Street",
  "Address2": "Solihull",
  "Address3": "West Midlands",
  "Postcode": "B91 3DG",
  "Email": "ljones@mailinator.com",
  "Mobile": "07890 123456",
  "Type": "sales",
  "IsVendor": true,
  "MarketingOptIn": true,
  "Position": [
    "General"
  ],
  "PotentialClient": true,
  "GeneralSearchCriteria": {
    "SearchType": "sales",
    "MinPrice": 300000,
    "MaxPrice": 450000,
    "FurnishState": [
      "part-furnished",
      "unfurnished"
    ],
    "MinBeds": 3,
    "MinBaths": 2,
    "PropertyType": [
      "House",
      "Bungalow",
      "Farm"
    ],
    "PropertyStyle": [
      "Detatched",
      "Terraced"
    ],
    "PropertySituation": [
      "Garden"
    ],
    "PropertyParking": [
      "Residents Parking"
    ]
  }
}

Response

Depending on the configuration of the client’s API, you will either get a message response ‘Applicant Imported’ (Pending import) or the Contact’s ID (Direct import). See the examples below:

...

Versions Compared

Old Version 1

New Version 2

Key

Contents

Authorisation

Retrieving Properties

A note about Reapit departments

Endpoint

Specifying Fields

Lettings Properties

Filtering results

Retrieving a Single Property

Getting an Unavailable Property

WSDL

The SOAP Request

Authorisation

Retrieving Properties

A note about Reapit departments

Method

Response

Specifying Fields

Lettings Properties

Retrieving a Single Property

Getting an Unavailable Property

Retrieving Contacts

Response

Page Comparison

Versions Compared

Old Version 1

New Version 2

Key

Contents

Authorisation

Retrieving Properties

A note about Reapit departments

Endpoint

Specifying Fields

Lettings Properties

Filtering results

Pagination

Retrieving a Single Property

Getting an Unavailable Property

WSDL

The SOAP Request

Authorisation

Retrieving Properties

A note about Reapit departments

Method

Response

Specifying Fields

Lettings Properties

Pagination

Retrieving a Single Property

Getting an Unavailable Property

Retrieving Contacts

Response