Find leads · Use case

How do I get real-time property alerts for my filters delivered to a webhook?

Use New Market Leads on the Casafari REST API. Sign in with POST /login, create a feed with POST /alerts-api/feeds (feed_name and filters), then register your endpoint with PUT /alerts-api/webhooks. The feed follows the property graph and sends signed alerts for new properties, price rises and cuts, reservations, removals from the market and sales.

Products: New Market Leads

#Short answer

A New Market Leads feed follows the property graph for a set of filters. It emits an alert when a matching property appears, rises or drops in price, is reserved, is removed from the market or is sold.

You create the feed once and register a webhook. Casafari then sends each alert to your endpoint, signed with a secret you can rotate.

#Steps

#Get a token with POST /login

1. Call POST https://api.casafari.com/login with your account email and password as JSON. It returns access_token and refresh_token (JWT).
2. Send Authorization: Bearer <access_token> on every request. Renew the token with GET /refresh-token using the refresh token. If that answers 401, log in again.

An integration or agent without a person uses an API client instead. The account owner creates it in Settings → API Clients on https://docs.api.casafari.com/. You exchange its client_id and client_secret at POST https://api.casafari.com/oauth/token with grant_type=client_credentials.

#Create the feed: POST /alerts-api/feeds with feed_name and filters

3. Send feed_name and filters. Only business_type is required inside filters (a key named operation is refused). Set the webhook first (PUT /alerts-api/webhooks): creating a feed before any webhook is set answers 409 with No webhook configured. The keys include location_ids, types, statuses, alert_subtypes, price_range, bedrooms_range, private, bank, auction and new_development. The full list is on the Create feed page.

#Set the delivery URL: PUT /alerts-api/webhooks

4. Send url. The operation takes a single url and no feed id: it sets the delivery URL for the account.

#Verify signatures; rotate with POST /alerts-api/webhooks/rotate-secret (24-hour grace unless immediate)

5. Check each delivery's signature with your signing secret before you trust it. The signature scheme is described on the Set webhook URL and Rotate signing secret pages, not in the sources of this page.
6. To rotate the secret, call POST /alerts-api/webhooks/rotate-secret. With immediate false (the default), the previous secrets keep working for a 24-hour grace window, which leaves time to update your verifier. Set immediate to true to skip the grace window.

#List, inspect and delete feeds: GET /alerts-api/feeds, GET /alerts-api/feeds/{feed_id}, DELETE /alerts-api/feeds/{feed_id}

7. GET /alerts-api/feeds lists your feeds. GET /alerts-api/feeds/{feed_id} returns one feed. DELETE /alerts-api/feeds/{feed_id} removes it.

#Polling alternative on v1: GET /api/v1/listing-alerts/feeds/{id}

8. Casafari client accounts can create a v1 feed with POST /api/v1/listing-alerts/feeds (name, filter).
9. They then read its alerts on demand with GET /api/v1/listing-alerts/feeds/{id} instead of receiving a webhook. See Get alerts by feed (v1).

#Example: new 3-bedroom apartments under 400,000 in Lisbon

Create the feed with POST /alerts-api/feeds:

{
  "feed_name": "Lisbon 3-bed apartments under 400000",
  "filters": { "business_type": "sale" }
}

With the webhook already set, add to filters the Lisbon location id in location_ids, the apartment type in types, alert_subtypes ["new"], 3 bedrooms in bedrooms_range and a maximum price in price_range. The accepted values are on the Create feed page.

The delivery URL, set beforehand with PUT /alerts-api/webhooks:

{ "url": "https://example.com/casafari/alerts" }

The fields of a delivered alert are documented on the Alert entity page. This page does not reproduce a sample delivery.

A Casafari client account can run the same filter on demand with POST /api/v1/listing-alerts/search. Replace <LISBON_LOCATION_ID> with the location id:

{
  "operation": "sale",
  "location_ids": [<LISBON_LOCATION_ID>],
  "types": ["apartment"],
  "bedrooms_from": 3,
  "bedrooms_to": 3,
  "price_to": 400000,
  "alert_date_from": "2026-10-01"
}

Asking an assistant on the Casafari MCP server to set up these alerts will not work, because alerts are not offered over MCP. An agent holding REST credentials, such as an API client, can make these calls itself.

#How to read the result

#One alert per property event

The property graph merges every advertisement of a property into one record. An alert is about an event on that property, not on one advertisement of it. A home advertised by several agencies produces one alert per event, not one per agency.

#Alert kinds and when each fires

• New property: a property matching your filters appears in the graph.
• Price rise or price cut: the property's price changes. Every change is recorded with its date in sale_price_history or rent_price_history.
• Reservation: the property's status becomes reserved.
• Removal from the market: the property stops being advertised.
• Sale: the status becomes sold (rented, for rentals).

In a feed's filters, alert_subtypes takes new, price_increased, price_decreased, reserved, delisted and sold. Use new properties and price cuts for prospecting, and reservations and sales to close out leads in your CRM.

#Limits

#REST only

The /alerts-api/* feed and webhook operations are available to Casafari clients with their Casafari account; self-serve access for new users is coming soon. You sign in with POST /login or an API client. The /api/v1/listing-alerts/* operations are for Casafari client accounts. Alerts are not offered over MCP.

#One webhook URL per account as exposed by PUT /alerts-api/webhooks

PUT /alerts-api/webhooks takes one url and no feed id. To route feeds to different systems, fan the deliveries out from your own endpoint.

#No delivery figures are published here

The sources publish no prices, quotas, delivery timing, retry policy, refresh frequency or SLA. For those, ask Casafari.

#Questions

All use cases