Developer guidelines

Introducing the Vitec Melger Hub API – a powerful tool for accessing and manipulating data within the Next Megler Suite. This API allows external systems and applications to seamlessly retrieve real-time information such as contacts and properties, enabling a wide range of use cases such as creating property presentations on the web, syncing data with a business intelligence system, or integrating contacts with an external CRM system. With its flexible and easy-to-use interface, the Vitec Melger Hub API is the perfect solution for streamlining data flow and unlocking the full potential of the Next Megler Suite.

Authentication

Authentication is a crucial step in accessing the Vitec Melger Hub API. Before making any API calls, partners must first register with Vitec to receive a unique partner ID and partner key, which act as the login credentials for the API. These credentials are used for HTTP basic authentication, which is a widely-used standard for user authentication on the web.

Upon registration, partners will receive a unique partner ID and partner key, which will be required for every API call. The partner ID serves as the username and the partner key serves as the password for the authentication process. For more information on basic authentication, please refer to the following resources:

Vitec administrates the rights of each partner, allowing the granular control of access to the different functions and customers within the API. For example, one partner may be granted read-only access to contacts, while another may have both read and write access to contacts and read-only access to properties. This allows for secure and efficient management of access rights within the API.

Making a call

Making API calls to the Vitec Melger Hub is straightforward and follows the principles of Representational State Transfer (REST) architecture, as defined by the Web API. Each API call is stateless and performs a specific action, such as fetching a property or saving a bid.

It is important to note that requests to the Hub API are made directly to the customer installation, bypassing the need for an intermediate caching layer. This ensures that the data retrieved is always up-to-date. To ensure optimal performance for all users, it is important to avoid making too many requests per second to a single installation. An example of unacceptable usage would be forwarding all requests made to a homepage to the Hub API.

Each API call requires the inclusion of login information, the function to be executed (specified by the URI), and any additional parameters as required by the function. Most functions also require the specification of a specific installation.

An example API call might look like this:

GET Accounts/Methods

The host/domain for the call will depend on the environment being used. Please refer to the Environments section for more information. In this example, the call is requesting to run the “Methods” function within the “Accounts” function group.

Provided you are authorized to access the information we will receive a JSON-formatted result (or an XML formatted if requested in the call)

For example:

[
  {
  "Verb":"GET",
  "Path":"Methods",
  "InstallationIds":["MSTEST"]
 },
 {
  "Verb":"POST",
  "Path":"HelloWorld",
  "InstallationIds":["MSTEST"]
 },
 {
  "Verb":"POST",
  "Path":"{installationId}/Estates/{estateId}/Documents",
  "InstallationIds":["MSTEST", "MSKZZ", "MSVIHLA"]
 }
]

Exact result differs between function of course.
You can chose if you want the result in JSON or XML format. JSON format is the default. If you prefer XML you can add the following header:

Accept: application/xml

Date and Time Handling

All date and time stamps in Hub are sent out with time zone stamps to avoid problems with incorrect parsing in different time zones. The format is according to ISO-8601, for more information, see https://en.wikipedia.org/wiki/ISO_8601.
For example, date for a contract meeting might be:

2023-01-25T14:00:00Z

To represent this date correctly for the current timezone (which normally is Norwegian) you need to convert it. In .NET you can use:

var norwegianDate = jsonDate.ToLocalTime();

if the code is executed on a computer in a Norwegian time zone. Similar functions exists in other programming languages.

Response (HTTP Status Codes)

The Vitec Melger Hub API returns HTTP status codes in its responses to indicate the outcome of an API call. These codes are easily machine-interpretable and provide a clear indication of whether a request was successful or if an error occurred. In the event of an error, the API will also return a JSON or XML error message to provide more detailed information about the issue.

The Hub API uses several different HTTP status codes to clearly communicate the outcome of a request. These codes are grouped into ranges, such as 2xx for successful requests and 4xx for client errors, and specific codes within each range to provide more granular information about the outcome. For example, a status code of 200 indicates a successful request, while a status code of 204 indicates that the request was successful but there is no content to return.

When handling responses from the Hub API, it is important to check for the range of status codes rather than specific codes, and use the specific codes for a better understanding of an error. The table below lists some of the commonly used status codes by the Hub API:

2xx – Successful requests
- 200 OK: The request was successful and the response contains the requested data.
- 201 Created: The request to create a new resource was successful.
- 204 No Content: The request was successful but there is no content to return.
4xx – Client errors
- 400 Bad Request: The request was malformed or missing required parameters.
- 401 Unauthorized: The provided credentials are invalid.
- 403 Forbidden: The provided credentials do not have sufficient permissions to access the requested resource.
- 404 Not Found: The requested resource could not be found.
- 412 PreconditionFailed: The call doesn’t meet existing preconditions. Ie, posting a tips with a postal code that isn’t Norwegian or isn’t within the range that the customers accepts tips for.
- 413 RequestEntityTooLarge: The upload of an image or a document is too large. 413 is also returned when a URL is used and the content exceeds the maximum limit. The default value is 50 MB, the limit is configurable and might be changed if necessary.
- 415 UnsupportedMediaType: The given media isn’t of the expected type. For example if you send a pdf
  to an image saving function or if you specify that you want to save a pdf throught post document
  but the data isn’t a pdf document.
5xx – Server errors
- 500 Internal Server Error: An unexpected error occurred on the server.
- 503 Service Unavailable: The server is currently unable to handle the request due to maintenance or capacity issues.
- 504 Gateway Timeout: The customer service could not be reached.

It’s important to keep in mind that APIs can change their codes, and developer should check the API documentation for the most up-to-date information about the codes returned by a particular API.

InstallationId and EstateId

Each installation has one database but can contain many customers / offices. To identify which database information should be read from or written to an InstallationId needs to
be provided. This information is normally provided among other relevant information from Vitec.

Installationid consists of a prefix MS followed by a short database reference. Installationid is alphanumeric and can be a maximum of 27 characters.

EstateID identifies the property on which to perform the operation and is the estates GUID. EstateId is alphanumeric and the maximum length is 36 characters. The EstateId is visible for the real estate broker on the “Oppdragsavtale” page in Next.

Rate Limits

To ensure optimal performance for all users and protect customer systems from excessive requests, the Vitec Melger Hub API enforces throttling limits on the number of requests that can be made by a partner to a customer. Any requests that exceed these limits will be immediately returned with a response code of 429 and will not be processed.

The maximum number of requests per partner per installation ID are as follows:

Per second: 20
Per minute: 600 (equivalent to an average of 10 per second)
Per hour: 10800 (equivalent to an average of 3 per second)

It’s important to keep in mind that these are maximum numbers and usage close to these limits should be avoided. In case of high usage, the integration should consider increasing the use of push subscriptions which allows you to receive real-time updates of data, this way the number of requests is reduced.

It’s important to keep in mind that these limits can change and that you should check the API documentation for the most up-to-date information about the throttling limits.

Additionally, The API will return a Retry-After HTTP-header when the status code is 429. The value indicates how many seconds the partner should wait before making another request to the same InstallationId.

Partners should also be prepared to handle the HTTP status code 429 and back off their requests accordingly. In case of reaching the limit, partners should consider implementing retries with exponential backoff to avoid overwhelming the API.

Security

Security is a top priority for the Vitec Melger Hub API. To ensure that data is protected and only accessible to authorized parties, it is important to follow best practices when making API calls.

The Hub API is designed to be called from server-based functions, and calls should never be made directly from a web browser. This is because making calls directly from a browser exposes the partner ID and partner key, which could potentially be intercepted by an attacker. To prevent unauthorized access, all API calls must be made securely using Transport Layer Security (TLS) version 1.1 or later.

The API uses a wildcard certificate for the domain *.megler.vitec.net, which is updated biannually. It is important to note that no information or heads-up is sent before a renewal, partners should be prepared to update their certificate accordingly.

Additionally, it’s important to use the HTTPS protocol for all calls, and make sure that the certificate is verified and is coming from a trusted source. When handling sensitive data, such as personal information, it’s important to encrypt the data in transit and at rest.

It’s important to keep in mind that security measures are constantly evolving and developer should check the API documentation for the most up-to-date information about the security measures for a particular API.

Error Handling

Proper error handling is crucial when working with the Vitec Melger Hub API, as there is no guarantee of an error-free connection between partners, clients, and the API. To ensure that your solution is robust and can handle unexpected errors, it is important to implement proper error handling mechanisms.

When a call to the API fails, a well-formatted response should be shown to the user, providing clear information about the error and possible next steps. Additionally, it’s important to implement retry handling mechanisms in case of failures. For example, if information can’t be written, it should be stored for retrial. Retries can be sent on an increasing schedule, starting with a 5-minute interval and increasing to a maximum of 4 hours.

In case of a call failing for a couple of days, the owner of the system should be notified to handle the situation. It’s important to have monitoring mechanisms that can detect and alert when there is an issue with the API calls.

It’s important to note that the Hub API does not include retry handling since it can only guarantee that information can be written if it actually succeeds. Therefore, it’s important to handle retries on the client side.

Key and password Management

Any secret keys or passwords used to access Hub must be stored so it can’t be reached by a third party, preferably encrypted. Store secrets so they are easy to update should the need arise. Your hosting provider will typically have a safe storage for secrets needed by your program. Use it!

Where to start?

After successfully registering with Vitec and receiving a partner ID and partner key, you have been granted access to the Vitec Melger Hub API. To get started, we recommend making a call to the GET Accounts/Methods function. This function allows you to retrieve the list of customers and functions that you have the rights to access, providing a good starting point to confirm that you have the necessary credentials and that your system is configured correctly to make API calls.

To make the call, include your partner ID and partner key in the request and confirm that you receive the expected response. This will confirm that you have the basic setup in place for making requests to the API, and you can then proceed to make more advanced calls to access the various functions and data available through the API.

Additionally, it’s recommended to check the API documentation to get familiar with the endpoints, parameters and the data that can be retrieved from the API, and also to test the different endpoints and parameters with a tool like Postman, this way you can get familiar with the API before integrating it with your system.

Single Call Tasks

Example of single call tasks are:
– Saving a document to a customer can be accomplished with one call. Simply call POST /<installationid>/Estates/<estateid>/Documents to save a document on a specific property.
– Register a new contact interested in a property by calling POST {installationId}/Estates/{estateId}/RegisterInterest

Multicall Tasks

In some cases, performing a task may require several API calls to be made. For example, when synchronizing all properties for sale to a web page, the following steps may be taken:

Make a call to GET Accounts/Methods to retrieve the ID’s of the offices that you have the rights to access information from. This approach allows your application to “auto-update” when additional rights are granted.
Loop through the offices and make a call to GET {installationId}/Estates with the desired filters to retrieve the relevant properties. Repeat this step until all estate lists for the offices listed in step 1 have been fetched. The returned list includes timestamps and unique IDs, which can be used to determine which properties are up-to-date and which have been removed.
Make a call to GET {installationId}/Estates/{estateid} to retrieve information about a specific property. Repeat this step until all properties listed in step 2 have been fetched.
Make a call to GET {installationId}/Estates/{estateid}/Images/{imageid} to retrieve a specific image. Repeat this step until all images listed in step 3 have been fetched.

An alternative approach is to use the push service which allows you to receive real-time updates of data, reducing the number of requests and improving the performance of the integration.

Push Service

The Vitec Melger Hub API offers a push service that allows registered partners to subscribe to real-time updates of data within the Next system. This service allows partners to receive notifications when the contents of certain API functions change, reducing the need for frequent data retrieval requests.

To get an overview of the push-activated functions, partners can use the “push” filter in the search field on the https://hub.megler.vitec.net/ website. To create a subscription, partners can use the Partner Portal. It is important to note that the partner is responsible for the initial collection of estate data from Next by utilizing GET Requests to the Vitec Hub API functions.

To receive push notifications, partners need to provide a webhook URL that accepts HTTP POST messages with a JSON payload whenever the data changes. The webhook URL needs to use the HTTPS protocol as some of the data may contain confidential information.

When a subscription filter matches an estate, and the estate is updated such that the subscription filter no longer matches, a “Remove” message is sent if (and only if) an “AddOrUpdate” message has been sent previously.

In the overview of the API functions on https://hub.megler.vitec.net/, functions described as “Pushaktivert” will match the functions in the list above. It’s important to keep in mind that the API may change over time and developer should check the API documentation for the most up-to-date information about the functionality and the usage of the API.

Push Filter

To get an idea of the possible subscription filter values, see

https://hub.megler.vitec.net/Help/Api/GET-installationId-Estates-estateId

Example below.

EstateStatus is defined as:

In this case, ”status=2” means estates for sale.

In the same way address.city can be used, see example below.

”Address” is defined as:

In this case, ”address.city={city}” can be used as a partner subscription filter.

If the partner subscription filter is enabled for sold estates, and a sold estate is archived or withdrawn, its status will be outside the interval set up for estates in Hub. A ”Remove” message will be sent, indicating that the subscription filter will no more match this estate, if an ”AddOrUpdate” has been sent previously.

Note that bid lists will be continuously updated and will never result in a ”Remove” message.

In general, a partner subscription filter can be enabled or disabled.

Event Data

This section contains some exampels of returned or pushed data and how to interpret them.

Example of information sent with ”AddOrUpdate” on an updated estate:


{
   "Reference": "OppdragTilSalgsOslo",
   "ObjectType": 1,
   "EventType": 1,
   "Data": ”{…}”
   "InstallationId": "MSNXTT",
   "ObjectId": "b950e7cc-26a4-4b87-9206-bb249367ac90"
}

”ObjectType” value 1 is estate while 2 is bids.
”EventType” value 1 is ”AddOrUpdate” while 2 is ”Remove”.
For examples of ”Data” content, please see https://hub.megler.vitec.net/Help/Api/GET-installationId-Estates-estateId.
The contents of the Data-property are a JSON-encoded string inside the JSON-message, so you will need to deserialize this string to escape quotes and access the data after receiving the POST.
”ObjectId” value is the unique estate id.

Example of ”Remove” update when the estate changes status to archived:


{
  "Reference": "OppdragSolgtOslo",
  "ObjectType": 1,
  "EventType": 2,
  "Data": null,
  "InstallationId": "MSNXTT",
  "ObjectId": "5ef2ab65-6ad9-4001-a9be-872f1c6e177a",
}

When you receive a message with EventType “2” (Remove), the Data field will in most cases contain “null”.

Example of bids update:


{
  "Reference": "Bud",
  "ObjectType": 2,
  "EventType": 1,
  "Data": "{…}",
  "InstallationId": "MSNXTT",
  "ObjectId": "b950e7cc-26a4-4b87-9206-bb249367ac90"
}

”ObjectId” is the unique id of the estate. For examples of ”Data” content, please see https://hub.megler.vitec.net/Help/Api/GET-installationId-Estates-estateId-Bids

Data will contain the exact same JSON as if you would have a direct call to to the Bids function. The JSON will be serialized into a string so that it can be stored in the JSON structure. This means that endpoint have to deserialize the Data string separately after it is received to get the JSON.

Response and Retries

The push service checks the status code returned by the receiving endpoint to determine if the push was successful. If the response from the partner’s endpoint has a HTTP status code in the successful range (200-299), the status is logged, and the push message is considered delivered.

However, the message is considered not delivered if one or more of the following situations occur:

The status code is not in the successful range
A connection could not be established with the provider endpoint
A complete HTTP response was not received within 60 seconds of issuing the request to the provider endpoint

In case the message could not be delivered, it will be retried in a loop. The first retry will be done after 1 minute, then 2, 4 minutes, 8 minutes, 16 minutes, and so on, until 4 hours. For each retry, a random wait time of 30 to 120 seconds will be added. This is done to ensure that a system that’s been unavailable for a couple of hours doesn’t receive several thousands of calls at the same second.

In the production environment, the message will be retried 30 times (i.e., roughly 4 days). In the test(QA) environment, it will be retried 10 times (i.e., roughly 12 hours).

It’s important for the receiving endpoint to implement proper logging and alerting mechanisms. This includes logging successful and unsuccessful deliveries of push messages, which can provide valuable insight into the performance of the service. Additionally, it’s important to set up alerting mechanisms to notify the relevant parties if no messages have been processed for an extended period of time, indicating a problem with the partner’s endpoint. It’s also important to monitor the rate of successful and unsuccessful deliveries and keep track of the number of retries that are happening, if there are too many retries that may indicate that the receiving endpoint is not functioning correctly. These measures can help prevent service disruptions and ensure that data is delivered to the partner in a timely manner.

The header information in a push request includes “X-Vitec-Next-Log” with a value that contains a GUID reference to the pushed information. This reference should be stored by the partner to make it easier to find errors when contacting Vitec Megler Customer Service.

Environments

https://hubtest.megler.vitec.net/
The test environment. Functions published in this environment are not subject to changes that breaks compability. Test installations of Next hooked up against the api so we’re able to test run the functions with
full functionality.
We can provide you with a test login to Next’s demo environment upon request. Together with Hub this is a full sandbox to test api calls in and to see the result in Next.

https://hub.megler.vitec.net/
The production environment