REST API

Owned by Diccon Towns (Unlicensed)
Last updated: Sept 23, 2020 by Fiona Hardy
6 min read

Representational State Transfer (Wikipedia) 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 API allows 3rd parties access to create, read and update Reapit clients' data via a set of defined endpoints.

 

Usage

In order to interact with the Reapit REST API you will need 3 things:

  1. An API endpoint, e.g. https://webservice.reapit.net/demo/rest/

  2. An API key, e.g. 8ed799bbe77c96311e71f64b99ec2ddde765d13a

  3. A client. This can be something as simple as a browser, a library 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:

ApiKey: [ ApiKey ]

e.g.

ApiKey: 8ed799bbe77c96311e71f64b99ec2ddde765d13a

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

Retrieving Properties

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

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.

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

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:

 

Note that related Reapit Agency Cloud 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 letting

  • Tenancies - tenancies for properties the contact is renting

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’

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:

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 /properties/{id} endpoint. E.g.

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

Getting an Unavailable Property

If a property is marked unavailable (e.g. No internet advertising is ticked on the property record in Reapit Agency Cloud), its data can still be retrieved by supplying the GetUnavailable parameter as true.

 

Retrieving Contacts

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

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 a comma separated list of required fields:

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. E.g:

 

Retrieving a Single Contact

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

If the contact is in the archive, the IncludeArchive will need to be supplied as true.

 

Importing a Contact

Contacts are imported using the POST /applicant method. E.g:

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 POST /applicant method

Contact Payload

The contact payload is supplied in the HTTP request body in JSON format. 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: