SOAP API

Owned by Diccon Towns (Unlicensed)
Last updated: Jan 21, 2020
7 min read

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

Usage

In order to interact with the Reapit SOAP API you will need 4 things:

  1. A WSDL URL, e.g. https://webservice.reapit.net/demo/?wsdl

  2. A Client ID, e.g. DemoUser

  3. An Password, e.g. 8ed799bbe77c96311e71f64b99ec2ddde765d13a

  4. 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.

  1. Pending Import - the contact’s data is stored in a holding table, ready for manual import by a negotiator.

  2. 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

Â