API and webhooks

Connect your other tools to the agency's data with an API key, and receive its events at your own address.

Keys are managed in Organisation › API, receiving addresses in Organisation › Webhooks.

Before you start

• The API and Webhooks sections only appear in the menu with the “Integrations” right (by default the administrator only).
• Both pages only open for the administrator. A manager or an agent who has been given the “Integrations” right sees the sections, but is sent back to the home page.
• Each feature must be included in your plan: “API” for keys, “Webhooks” for addresses (see Subscription and billing). Otherwise, the page says so and offers See plans.

The API

The API gives access to the data of your agency, and of it alone.

• Mandates are provided without the negotiation margin, commission or log.
• Each key is allowed 120 requests per minute and 20,000 per day.

The technical documentation

The API page shows the API address and a Documentation link. This link opens the API's public technical documentation, intended for your developer: each endpoint, its parameters, its responses, how to authenticate with the key and how to page through results. In production, it is at https://api.immobooking.be/api/v1/externe/docs.

Creating a key

1. Open Organisation › API.
2. On the New key card, enter the Key name (2 to 60 characters), for example “Agency website” or “Dashboard”.
3. Tick Can also write (create leads, move opportunities) if the tool needs to write. Otherwise, the key can only read.
4. Click Create key.
5. On the Your new key card, click Copy, then store the key somewhere safe.
6. Click I have copied the key.

Tracking and revoking keys

The Your keys list shows for each key its name, its beginning, the “Read” or “Read and write” badge, its creation date and its last use (or “Never used”).

1. Click Revoke next to the key.
2. Confirm. The message “Key revoked.” is shown.

Tools using this key lose access immediately; the other keys keep working. If your plan loses the “API” feature, all keys are refused.

Webhooks

A webhook sends a message to your tool's address for each event in the agency.

Adding an address

1. Open Organisation › Webhooks.
2. On the New address card, enter your tool's Address (https).
3. Tick at least one of the Events.
4. Click Save address.
5. On the Signing secret card, click Copy and give the secret to your developer.
6. Click I have copied the secret.

• The secret is only shown once. Your tool uses it to check that messages really come from ImmoBooking; the Verifying a message card explains how.
• Ten addresses at most.
• Possible refusals: “This address is not valid.”, “The address must start with https://.”, “This address points to an internal network: it is refused.”.

Managing an address

In Your addresses, each address carries the “Active” or “Paused” badge.

• Send a test: a test message is sent within the minute.
• Pause and Resume.
• Delete: no more messages are sent there, and the history of its deliveries is deleted.

Tracking deliveries

Under Latest deliveries, each message carries the status “Pending”, “Delivered” or “Failed”, the number of attempts and, where applicable, the time of the next attempt.

• Your tool must reply within 10 seconds with a success response. A redirect is not followed and counts as a failure.
• If it fails, the message is sent again 1, 5 and 30 minutes later, then after 2, 6, 12 and 24 hours, that is for nearly two days.
• After the last attempt, the failure is final. Replay puts the message back in the queue (“Delivery queued again.”).