Minimum viable integration

A "minimum viable integration" is an integration that complies with a minimum set of requirements that we consider essential for a successful user experience.

Use the following checklist to verify that your integration is compliant ready to go live. While this is not an exhaustive list, you should definitely be able to answer "yes" to all of the following items:

Self-service user authorization

Your application should allow users to manage the authorization process on their own. This ensures optimal user experience and reduces obstacles for users to start enjoying the benefits of your integration. Make sure you go through the Authorization Flow reference to understand how the OAuth2 flow works.

Access token management

By using OAuth2, your application should manage tokens seamlessly. This means that it must take into account the specifications of the OAuth2 protocol and the implementation that we provide you with. Make sure you handle access token expiration and are able to obtain new tokens using the refresh token. This should be transparent for users - if a token expires, users shouldn't even notice it. However, if a user revokes your application's access to his account, your application should behave accordingly (i.e. don't allow further operations until a new authorization is granted).

Taxonomy mapping

It's super important to make sure you have mapped our taxonomy to your own before going live. Certain parts of the taxonomy are mandatory and your application won't be able to publish adverts without them. Furthermore, categories and attributes contribute greatly to the quality of the ads that your customers will publish.

Feedback for validation errors

When things don't go as expected, it's important that users are aware of what went wrong. There are different types of problems and your application should be prepared to handle all failure cases. A couple of examples are field Advert payload and validation rules and publication errors.

Notification webhooks

We required that you implement a webhook handler so that you can more easily deal with the asynchronous nature of our API. Remember that publishing an ad takes some time, so instead of polling the API to know its status, you should wait for a notification in your webhook endpoint to get this information.

Custom contact information for agents

On our real estate Marketplaces, you can customize the contact information in ads. This is specific to the real estate market where a lot of agency networks need to publish ads with the contacts of individual agents. Make sure you go through the Publishing adverts section to understand how this is done.

Exact or non-exact location flag

Real estate agents are very sensitive to the publication of the exact location of their properties. Our API provides a flag to control this attribute and it's very important that your application exposes this option to users.

Leads integration (optional)

Integrating leads directly to your application ensures a great user experience because users can do more in one single place and don't have to constantly switch between platforms. To achieve a rich integration, your application should consume the Incoming Message notification and provide an interface for your users to see them.

Package Information (optional)

One of the points that cause most of the calls to the call center (local teams) is the non-publication of ads, and most of the time, this situation happens because the customer has no active package or still has unpaid invoices.
To mitigate these calls, we strongly recommend that you develop integration with the Profile API.
You can ensure a better user experience displaying clients package information or developing warning messages or even notifications to the customer when the payment term approaches.