Watchlists and alerts

Watch homes by Zillow link, zpid or address. Each one is checked about once a day, and you get an event when its price, status, Zestimate, photos or rent Zestimate change: by signed webhook, a daily email, or the API.

Billing and limits

Each daily check of a watched home is a lookup: 1 credit, or free when the home comes from the 24-hour cache. Checks use your lookups like any other call (included, then prepaid credits, then usage past your plan) and pause when they run out.

The limit counts every home on all your watchlists, paused ones included. Adding a home past it returns 403 watch_limit_reached before any lookup, so it costs nothing.

How checks work

• Watched homes are checked about once a day. There is no guaranteed time of day.
• Each check is a lookup through the same gate as the API: 1 credit when it runs live, free when the home comes from the 24-hour cache. Checks use your plan's lookups, its spending limit and the service's daily limits.
• When your lookups or your optional spending limit run out, checks pause and the dashboard says why. Nothing is billed while paused. We try again about every 6 hours, and you can resume at once with POST /watchlists/resume.
• A check compares the home with its last snapshot: price, status, Zestimate, rent Zestimate and photo count. Only those fields are kept.
• Paused homes and paused watchlists aren't checked. After a downgrade, homes past the new plan's limit aren't checked until you remove some.
• Events are kept for the dashboard and GET /watchlists/events. With a webhook URL set, each event is also sent to it; with the email digest on, you get one email a day listing the day's events.

Events

Endpoints

Base https://api.propertiesapi.com/v1, with your key in the x-api-key header. The same watchlists are on your dashboard.

curl "https://api.propertiesapi.com/v1/watchlists" -H "x-api-key: $PROPERTIESAPI_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Austin flips","price_change_pct":2}'

curl "https://api.propertiesapi.com/v1/watchlists/wl_.../homes" -H "x-api-key: $PROPERTIESAPI_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://www.zillow.com/homedetails/.../12345_zpid/"}'

Webhooks

• Each event is a POST of JSON to your https webhook URL: { id, type, created_at, data: { watchlist_id, home_id, zpid, address, detail_url, old, new, change, change_pct } }. type is watch.<event type>, e.g. watch.price_change.
• X-PropertiesAPI-Event-Id is the event id, the same on every retry: use it to ignore duplicates.
• X-PropertiesAPI-Signature is t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your signing secret>. Check it against the raw body and refuse timestamps older than 5 minutes.
• Answer with any 2xx status. Anything else, or no answer within 10 seconds (DNS included), is retried after about 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marked failed in the delivery log.
• An endpoint that answers slowly (5 seconds or more) or fails is backed off: your other events wait, starting at 1 minute and doubling on each slow or failed answer, up to 6 hours. A fast 2xx resets it. Events go out in the order they happened, at most 2 at a time per account.
• The URL must be https on port 443 (or 8443) and point to a public internet address. Private, loopback, link-local and cloud metadata addresses are refused when you save it, and again before every delivery and every redirect.

curl -X PATCH "https://api.propertiesapi.com/v1/watchlists/settings" -H "x-api-key: $PROPERTIESAPI_KEY" \
  -H "content-type: application/json" \
  -d '{"webhook_url":"https://example.com/hooks/propertiesapi"}'
curl -X POST "https://api.propertiesapi.com/v1/watchlists/settings/secret" -H "x-api-key: $PROPERTIESAPI_KEY"   # shown once

{
  "id": "evt_0000000000000000",
  "type": "watch.price_change",
  "created_at": "2026-10-21T14:05:00.000Z",
  "data": {
    "watchlist_id": "wl_0000000000000000",
    "home_id": "wh_0000000000000000",
    "zpid": "0000000",
    "address": "1600 Main St, Austin, TX 78701",
    "detail_url": "https://www.zillow.com/homedetails/1600-Main-St-Austin-TX-78701/0000000_zpid/",
    "old": 525000,
    "new": 510000,
    "change": -15000,
    "change_pct": -2.86
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received (a string), secret: your whsec_ signing secret
export function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // older than 5 minutes
  const want = createHmac("sha256", secret).update(`${m[1]}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}

Daily email

Turn on the email digest on your dashboard or with PATCH /watchlists/settings. You get at most one email a day, from login@propertiesapi.com, listing the changes found since the last one. No changes, no email.

Errors

Other errors are the same as for every v1 call. See errors.

Data is provided as-is, as shown on public Zillow pages at the time of each check, without any guarantee of accuracy or completeness. Zillow is a trademark of Zillow, Inc. PropertiesAPI is an independent service and is not affiliated with, endorsed by or sponsored by Zillow.