SOAP API
Introduction
SOAP (abbreviation for Simple Object Access Protocol) is a 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 methods.
Contents
- 1 Contents
- 2 Usage
- 3 WSDL
- 4 The SOAP Request
- 5 Authorisation
- 6 Retrieving Properties
- 6.2 Method
- 6.3 Response
- 6.4 Specifying Fields
- 6.5 Lettings Properties
- 6.6 Pagination
- 7 Retrieving a Single Property
- 8 Retrieving Contacts
- 9 Retrieving a Single Contact
- 10 Importing a Contact
- 10.1 Contact Data
- 10.2 Applicant Criteria
- 10.3 Response
- 10.3.1 Pending import
- 10.3.2 Direct import
Usage
In order to interact with the Reapit SOAP API you will need 4 things:
A WSDL URL, e.g. https://webservice.reapit.net/demo/?wsdl
A Client ID, e.g. DemoUser
An Password, e.g. 8ed799bbe77c96311e71f64b99ec2ddde765d13a
A client. This can be the Reapit Web Service Test Tool, a library (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 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:
<?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:
<SOAP-ENV:Header>
<ns2:ClientID>[ ClientID ]</ns2:ClientID>
<ns2:Password>[ Password ]</ns2:Password>
</SOAP-ENV:Header>
e.g.
<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:
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
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.
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.
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:
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’:
Pagination
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:
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:
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:
Retrieving Contacts
Contacts are retrieved using the GetContacts method.
Searching for Contacts
The Reapit API provides a number of parameters by which Contacts can be searched, these are ID, Email and Phone. E.g:
Specifying Fields
To request specific fields in the response, the RequiredField parameter can be supplied with an array separated list of required fields:
Note that related RPS roles can be requested, these are:
Searches - Live applicant searches
InactiveSearches - Dormant applicant searches
GeneralPropertiesForSale - Properties the contact is selling.
GeneralPropertiesToLet - Properties the contact is lettings.
Tenancies - Tenancies for properties the contact is renting.
Pagination
If large amounts of data are being requested (e.g. many fields and/or large numbers of contacts), it’s best to paginate the results to retrieve the results in chunks. This is achieved with the Offset and Limit parameters:
Searching the Archive
When searching for contacts the archive can also be included by supplying the IncludeArchive parameter, set to true.
Retrieving a Single Contact
Single contacts are retrieved using the GetContact method.
If the contact is in the archive, the IncludeArchive will need to be supplied as true.
Importing a Contact
Contacts are imported using the ImportApplicant method.
There are two behaviours to this method, depending on the configuration of the client’s API.
Pending Import - the contact’s data is stored in a holding table, ready for manual import by a negotiator.
Direct Import - a contact record (and any related applicant record, if required) is created immediately on the system.
Which of these two options is configured will determine the response you get from the ImportApplicant method
Contact Data
The contact data is supplied in the SOAP request body. For example:
Applicant Criteria
If the contact has applicant search criteria that also needs to be saved, this is supplied in a < Department >SearchCriteria
property of the payload, e.g. GeneralSearchCriteria
. An example payload with attached search criteria is show below:
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:
Pending import
Direct import
Â