Alert

An Alert is a saved search that produces AlertEvents when new listings match. Events are delivered via an EventDestination according to the configured rules.

From ingestion to notification

When an ingested listing matches an alert, it produces an AlertEvent. Each event can trigger one or more notifications, delivered to the configured destination.

Listingingested

matches

Alert

produces

AlertEvent

triggers

Notification

delivered to

Destinationwebhook

Attaching a destination

Two options:

On the fly — pass webhookUrl into POST /alerts. If a destination with that URL already exists on your account it is reused, otherwise it is created. Simplest way to get started, or to give each alert a different URL.
From an existing destination — create it via POST /account/event-destinations, then reference it by eventDestination. Handy when several alerts share one destination, which you then manage in a single place.

POST /alerts

{
  "name": "2-bedroom apartments in Paris",
  "notificationDestination": { "webhookUrl": "https://your-server.com/webhooks/alerts" },
  "notificationConfig": { "rules": [{ "eventType": "NEW_MATCH" }] }
}

The response carries the signingKey only if this is the first webhook destination of your account. Store it: it is never returned again.

Alert schema (response)

Field	Type	Description
`id`	string (uuid)	Read-only identifier
`name`	string \| null	Alert name, surfaced in the dashboard
`enabled`	boolean	Whether the alert is enabled (disabled alerts skip delivery but stay indexed)
`criteria`	`CriteriaNode` \| null	Recursive criteria tree (same shape as `POST /properties`)
`notificationConfig`	`AlertNotificationConfigDTO` \| null	Notification rules (see below)
`eventDestination`	string (IRI) \| null	Linked destination, e.g. `/account/event-destinations/{id}` (read-only)
`signingKey`	string \| null	HMAC key for signing webhooks, prefixed `whsec_`. Returned once only, when the request creates the first webhook destination of your account. See Notifications.
`createdAt` / `updatedAt`	string \| null	ISO 8601

Request schema (`AlertRequestDTO`)

POST /alerts and PUT /alerts/{uuid} share the same body. The table describes each field as POST reads it; on PUT an omitted field keeps its stored value — see Updating an alert below.

Field	Type	Description
`name`	string \| null	Optional on create; a name is generated from criteria when omitted. Max 255 chars.
`enabled`	boolean	Default `true` on create.
`criteria`	`CriteriaNode` \| null	Recursive tree — see Filtering. Omit on create to match every property.
`notificationConfig`	`AlertNotificationConfigDTO` \| null	`eventType`, `scope` and variation-window rules. Omit on create and the alert never notifies.
`notificationDestination`	`NotificationDestination` \| null	Destination — provide exactly one of the fields below. Omit on create to use your account default destination; if your account has none yet, the request is rejected with a `422`. Your first destination becomes the default automatically — see Notifications.

`NotificationDestination` — oneOf

Field	Type	Effect
`eventDestination`	string (IRI)	Link an existing `EventDestination`, e.g. `/account/event-destinations/{id}`.
`webhookUrl`	string	Create or reuse a webhook `EventDestination` for this URL.

Updating an alert

PUT /alerts/{uuid} changes only the fields the body names. Each field is in one of three states:

The body	Result
field omitted	the stored value is kept, unchanged
field sent as `null`	the value is cleared: `name` is emptied, `criteria` matches every property again, `notificationConfig` stops every notification, `notificationDestination` goes back to your account default destination
field sent with a value	replaces the stored value. `criteria` is replaced as a whole tree, never merged key by key

enabled is a boolean and cannot be null: omit it to keep the current value.

To widen an alert to every property, send "criteria": null explicitly. A PUT without criteria keeps the current filter.

Notification rules (`AlertNotificationRuleDTO`)

Each rule targets an eventType. Without a rule, an event is never sent: add one rule per event you want. One rule per eventType: a duplicate gets a 422.

Field	Type	Description
`eventType`	string (enum)	Required. Which event notifies (see below).
`scope`	`PROPERTY` \| `LISTING`	Default `PROPERTY`: one notification per property — an identical change published on several listings of the same property notifies once. `LISTING`: one notification per listing — each new listing on a property you already follow triggers its own `NEW_MATCH`.
`variationPercent`	`[{ gte, lte }, …]`	Only for `PRICE_CHANGE`: list of variation ranges, in percent (see below). Empty or omitted: every price change is sent.

`eventType`	Trigger
`NEW_MATCH`	A property enters your search perimeter
`PRICE_CHANGE`	Its price changes
`OTHER_CHANGE`	Another attribute changes
`EXPIRED`	The property leaves the market
`REACTIVATED`	The property returns to the market

Until 2026-10-20, a rule still carrying the former enabled field is accepted: false drops the rule, true is ignored. After that date, the field is refused with 400, like any unknown field. To stop receiving an event, remove its rule.

Variation window for `PRICE_CHANGE`

variationPercent is a list of ranges in percent: [{ "gte": …, "lte": … }]. A drop is negative. The rule fires as soon as one range contains the variation. Omit the list, or send [], to receive every price change. A bare object outside a list gets a 400.

Need	`variationPercent`
Drop of at least 5%	`[{ "lte": -5 }]`
Drop between 20% and 40%	`[{ "gte": -40, "lte": -20 }]`
Rise of at least 10%	`[{ "gte": 10 }]`
Move of at least 5% in either direction	`[{ "lte": -5 }, { "gte": 5 }]`

Endpoints

POST /alerts — create (response includes signingKey when it creates the first webhook destination of your account)
GET /alerts — list
GET /alerts/{uuid} — detail
PUT /alerts/{uuid} — update
DELETE /alerts/{uuid} — delete
GET /alerts/{alertUuid}/events — AlertEvents produced by this alert
GET /alerts/{alertUuid}/events/{uuid} — event detail

See also: Notifications for EventDestination and delivery.

Alert

On this page