How to integrate Arthur to your website

Arthur Online’s open API allows your own systems and websites to communicate with Arthur, either by retrieving data you have in Arthur or even creating data in Arthur via another system. A common use of this feature is if you want to market your properties and units on your website then that is exactly what you use the API for. 

Getting started

Everything you need to know about the API can be found at https://developer.arthuronline.co.uk. This document serves to break it down into simple first steps so you can start using it with no hassle. The API uses JSON format for all API responses, as well as for request bodies when creating/updating data. Make sure you have the header ‘Content-Type: application/json’ in all of your requests to make sure our API knows how to read your request data.

Authentication

To make sure your data is secure and only you can access it, we require some form of authentication to be able to retrieve/alter data on your account. This is your system’s way of ‘logging in’ to our API, in the same way you would log in through your browser to access your account. To get a token, you can follow these simple steps:

1. Go to your Dashboard in Arthur. From there select ‘Settings’, then under Account Settings, you should see OAuth Applications
2. Once on OAuth applications note down your Entity ID found in the orange message at the top – you will need this later for any API calls.
3. Select ‘Add Application’ in the top right.
4. Enter the following 4 fields:
   1. Name – The display name of your application
   2. Description – Describe what the application does and what it will be used for
   3. Website – A URL where you can find more information about your application (does not necessarily have to be the website you are integrating with)
   4. Callback URL – This is a URL that will be redirected to after performing step 1 of authorizing. It should be a public endpoint that can retrieve the ‘code’ variable from the query parameters. If you are authorising on the same machine as your server (e.g. a local development environment) then you can use localhost as the domain for this.

When you submit you should see your OAuth Application in your list with a Client ID and Client Secret – note these as they will also be needed for performing the last steps of authentication. You should have everything you need now to set up the Authorisation flow. Please follow this step-by-step guide to getting access tokens: https://apidocs.arthuronline.co.uk/apis/(apispage:authentication).

Calling the API

Now you should have both the access token and entity ID variables from the previous section, which means you can start making API calls! You can either use postman or a simple curl request. Here is one you can paste into your terminal to check the token and entity ID are correct, making sure to replace the entity ID and access token respectively: curl -X GET \ -H 'Content-Type: application/json' \ -H 'X-EntityID: YOUR_ENTITY_ID' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ https://api.arthuronline.co.uk/v2/properties This should return a JSON object with two variables: status and data. If you have any properties on your account, then data will hold a JSON representation of each of your properties.

Common use cases

Here are a couple of examples that we see requested most frequently when our API is being used.

1. Marketing properties on your website

To retrieve all listings, use the following endpoints: GET https://api.arthuronline.co.uk/v2/units - Get all units (these are individual rentable spaces) If you also want to list properties that group by units (e.g. list building A, then when you select it you can see Units A and B under that property) then you can use the following endpoints instead: GET https://api.arthuronline.co.uk/v2/properties - Get all properties. GET https://api.arthuronline.co.uk/v2/properties/{property_id}/units - Get all units for a particular property. To get the property_id variable it is returned by the first /properties call.

2. Booking viewings

To create a viewing there are two steps. See the documentation at https://developer.arthuronline.co.uk for a full list of fields. First, you need to create an applicant using the following request: POST https://api.arthuronline.co.uk/v2/applicants { “first_name”: “John”, “last_name”: “Doe”, “email”: [email protected], “mobile”: “+442071124860” } If successful you should retrieve some data back with an ‘id’ field. You will need this for the next step, which is to create the viewing: POST https://api.arthuronline.co.uk/v2/viewings { “applicant_id”: {applicant_id}, “unit_id”: {unit_id they wish to view}, “viewing_date”: “2020-06-01”, “viewing_time”: “12:00”, “notes”: “Hi I would like to see this property it looks lovely in the pictures” } This will create viewing for the specified unit and applicant, with optional viewing date, viewing time and notes if you allow the user to specify those extra options.

Integrating to a WordPress website

Whilst you can build your own integration to your WordPress website, a WordPress plugin is also commercially available. The plugin is provided by Property Hive. Property Hive has no affiliation to Arthur and is an independent provider.

Is there anything you can't integrate?

At the moment, you are unable to connect to a Rightmove BLM feed. All other integrations should be possible, either directly or by building middleware to translate the data into the correct format.

Please note: whilst Arthur is happy to help you with any queries when integrating to your website, you are responsible for ensuring your website is compatible, and completing the work itself. If you require additional endpoints to be created, we are able to create these, but a fee may be incurred.

Can Arthur recommend a web developer?

We have worked with  https://www.servondesign.co.uk/. They have worked extensively with clients using our API. Please note we take no responsibility for any works