Whise API

How to use the Market Place?

WHISE API allows you to get data in order to build websites. You can perform only read operations (get data) without updating, except for update of contact which is used for inserting prospects. You have a WHISE marketplace account as a service supplier. Real estate agents don't have this view. The most important part of the process is activating a connection with you client. In order to do so, please send their ClientID and OfficeID to (helpdesk@whise.eu). Only then you will be able to get a token and access the data. This process will be automated in the near future.

Definitions

Please find here the definition of terms frequently used in this documentation:

• user: a person that use the WHISE application
• office: a group of users that work functionally or geographically together, this means an office in a separate location or a separate division. In most cases, the offices are legally independent and you will invoice the offices separately.
• client: this is the level above office, so a client contains one or more offices usually using the same commercial name. In this documentation we also use the term 'customer' for designating clients.
• estate: this is our technical name for property
• details: the main fields related to the estates (address, price ...)
• subdetails: additional fields related to the estates (construction year, energy consumption ...)
• contact: this is our technical name for the persons involved in the transactions of the properties, ex: the owners, the potential buyers, the potential tenants or any other type of persons (insurance brokers, media, real estate agents ...)

Statuses

At WHISE, we pay a lot of attention to the quality of the services we propose to the users. Therefore, we ask you to go through different steps in order to make sure you understand the way the Market Place works and your services meet our expectations.

Status 'Pending'

When you have just created your Market Place account, you are in status 'pending'. At this stage, we let you become familiar with the application. Please find a list of actions you need to perform in order to make sure you are using the system correctly (see also the detailed explanation later):

1. Make tests (like GetEstates or CreateContact) on your dummy data available without any activations. The bearer token you can get by providing your credentials in Marketplace > Dashboard > Activations or my making a call Authentication by password described below.
2. Fill your marketing data in the tab Marketing.
3. Activate a gateway with a real client.

Status 'Testing'

After activating a real client you can test the actual data. Please note that you can see all activation requests in the dashboard, widget 'activation of clients'. It is a very convenient place to get your tokens from. You can also deactivate a client if is necessary.

1. Make sure the transfers are technically OK (you will be able to detect errors via the logs)
2. Test more complicated situations like CreateContact when a contact already exists, of getting data of projects.

Status 'Production'

This is a rather symbolic status for webdesigners, yet important for other types of marketplace providers.

Tabs

All the other views but Marketplace are standard Whise views, that can be seen by our clients. Please check Whise Academy in order to familiarize yourself with the application. (https://fr.whiseacademy.eu/) Let's focus now on the Marketplace view.

Tab Settings

After the creation of the account, the application opens at the page Market Place / Settings.

Description of the page

On the left side, you see the name of your service, the status ('Pending' in this case) and the contact person.

Tab Marketing

The information filled in this tab will help you promote your brand and product correctly through the application of WHISE.

Logo

• Upload your logo

•   The format must be png or jpeg
  

  PLEASE BE AWARE THAT THE LOGO ONLY APPEARS IN THE UI WHEN YOU ARE A PREMIUM ACCOUNT

  Description

  There are 2 descriptions you have to fill

• Short description: this is the commercial text that will be displayed to the user when ordering your service in the 'Admin' -> 'Advanced' -> 'Marketplace Suppliers'

•   Activation request description: this is the commercial text that will be displayed to the user before activating your service. It will push the users of WHISE to activate your service.
  

  Both texts have to be filled in 3 languages

  Congratulations, you are now set up!

Variables and collections

This API allows you to obtain data from WHISE in a simple, programmatic way using HTTP requests. The easiest way to get started using the WHISE API is to use our Postman request collection. Postman is a free-to-download tool for making HTTP requests. The following steps outline the necessary actions in order for you to install Postman, configure Key presets and gain certainty that everything is working as it should be. If you prefer, you can explore our API with other tools like curl.

Install Postman and import request collection

• Download the version of Postman required for your platform
• Install Postman
• Open Postman
• Click Import, click Link and specify this Postman collection url
• Click the Eye icon to setup an Environment
• Click Add
• Enter an Environment name. for example, WHISEAPI
• Enter key url and value https://api.whise.eu
• Enter key username and value your_whise_username
• Enter key password and value your_whise_password
• Click Save
• Get your token by running Token/Authentication by password from WHISEAPI collection

Lookup data

Whise internal Ids for different system lookup data are available for download as simple JSON files:

• Base contact type - English | French | Dutch | Spanish
• Base document type - English | French | Dutch | Spanish
• Category - English | French | Dutch | Spanish
• Client status
• Contact status
• Contract type - English | French | Dutch | Spanish
• Country - English | French | Dutch | Spanish
• Detail - English | French | Dutch | Spanish
• Detail type - English | French | Dutch | Spanish
• Environment type
• Estate availability - English | French | Dutch | Spanish
• Estate display status
• Estate fronts
• Estate state - English | French | Dutch | Spanish
• Estate status
• Export media status
• Language - English | French | Dutch | Spanish
• Office status
• Purpose - English | French | Dutch | Spanish
• Purpose status - English | French | Dutch | Spanish
• Subcategory - English | French | Dutch | Spanish
• Subdetail type
• Subdetail - English | French | Dutch | Spanish
• Subdetail enum - English | French | Dutch | Spanish
• Log category - English | French | Dutch | Spanish
• Energy label

Authentication

The API uses Bearer authentication with JWT token (a compact and self-contained way for securely transmitting information between parties as a JSON object).
The client must send this token in the Authorization header when making requests to protected resources:

    Authorization: Bearer <token>

You can create a JWT token via our get token method.

Pagination

A lot of the time, when you're making calls to the REST API, there'll be a lot of results to return. For that reason, we paginate the results to make sure responses are easier to handle. The pagination used in our public API is LIMIT OFFSET pagination.

The LIMIT clause is used to limit the number of results returned in the response. The OFFSET clause sets the first position to return from the results. We specify with the OFFSET where to start a page.

Example: We have 100 properties in the system. To get 10 properties in places 40 – 49, send the following:

    limit=10&offset=40

Throttling policy

In cases where the API's endpoints responses are processed and delivered with a certain latency or the amount of calls is too big for the capacity of the service to respond to all the real time requests, the API has introduced throttling rules according to the needs of each type of such a demanding endpoint. We can mention here heavy operations like creating / updating properties, to give only some straightforward example. In general, when the API calls are throttled, the metrics of current applied limitations are included in the calls responses as headers information which is helping the partners to calibrate their requests rate. The following common headers can be provided in the response:

• X-RateLimit-Limit - number of maximum allowed requests (rate limit)
• X-RateLimit-Window - time window in seconds for which the rate limit is in effect
• X-RateLimit-Remaining - number of remaining requests
• X-RateLimit-Reset - time at which the rate limit resets

Webhook for real time data syncronization

To receive information when something is updated in Whise you can setup a special webhook page on your side that will receive the update. The received payload will have the following format:

{"clientId":x,"officeId":x,"userId":xxxxx,"events":[{"name":"estate_update","objectId":xxxxxxxx,"officeId":xx}]}

where the name of the event can be one of the following:

• calendar_update
• calendar_created
• estate_update
• estate_created
• user_update
• office_update
• region_update
• group_estate_shared
• group_estate_unshared

Where necessary, an additional "objectId" will be sent containing the Id of the created/updated data object. The "officeId" next to it represents the office Id of the object, not allways the same like the office of the user which is triggering the event.

You can fill the url of the webhook in your Marketplace > Settings tab.

API Endpoints