Listing freshness

Owner “still available?” pings with a tracked link, stale listings, price-revision nudges and their settings.

GET/v1/listing-freshness/listings

Stale listings

`stale`: flagged stale, longest first · `due`: not confirmed within the ping interval · `price`: nudged for a price revision. Within the caller’s listing scope; keyset-paginated.

Access: API key with properties:read, or a member session. Permission properties.view.

Parameters

viewquery: "stale" | "due" | "price"
cursorquery: string
limitquery: integer

Response · 200

datarequired: array of StaleListing
metarequired: object
meta.next_cursorrequired: string or null
Opaque cursor of the next page; null on the last page.
meta.has_morerequired: boolean
meta.moderequired: "off" | "built_in" | "automation"
meta.stale_after_daysrequired: integer

Request

curl -X GET 'https://api.propzolo.com/v1/listing-freshness/listings' \
  -H 'Authorization: Bearer pz_live_…'

Response example

{
  "data": [
    {
      "id": "cmusrceel0000q7kaafxqi1om",
      "ref_code": "string",
      "title": "string",
      "status": "string",
      "listing_type": "string",
      "price": 850000000,
      "rent_amount": 850000000,
      "owner": {
        "id": "string",
        "name": "string",
        "phone": "string"
      },
      "has_owner": true,
      "listed_by": {
        "id": "cmusrceel0000q7kaafxqi1om",
        "name": "string"
      },
      "verified_at": "2026-10-06T05:30:00.000Z",
      "stale_at": "2026-10-06T05:30:00.000Z",
      "price_nudged_at": "2026-10-06T05:30:00.000Z",
      "days_since_confirmed": 0,
      "last_check": {
        "id": "cmusrceel0000q7kaafxqi1om",
        "status": "string",
        "channel": "string",
        "blocked_reason": "string",
        "sent_at": "2026-10-06T05:30:00.000Z",
        "opened_at": "2026-10-06T05:30:00.000Z",
        "responded_at": "2026-10-06T05:30:00.000Z"
      }
    }
  ],
  "meta": {
    "next_cursor": "string",
    "has_more": true,
    "mode": "off",
    "stale_after_days": 0
  }
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

GET/v1/listing-freshness/settings

Listing freshness settings

Access: Signed-in members only (web or Android session) — not for API keys. Permission settings.inventory or settings.view.

Response · 200

datarequired: ListingFreshnessSettings
metarequired: object

Request

curl -X GET 'https://api.propzolo.com/v1/listing-freshness/settings' \
  -H 'Authorization: Bearer pz_live_…'

Response example

{
  "data": {
    "mode": "off",
    "ping_interval_days": 7,
    "channel": "auto",
    "max_pings_per_day": 1,
    "stale_after_days": 7,
    "hide_stale_from_matching": true,
    "hide_stale_from_shares": true,
    "notify_agent": true,
    "price_nudge_days": 0,
    "price_nudge_max_enquiries": 0,
    "mandate_notice": true
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

PATCH/v1/listing-freshness/settings

Change listing freshness settings

stale_after_days must exceed ping_interval_days; price nudges after at least 15 days (or 0 for none).

Access: Signed-in members only (web or Android session) — not for API keys. Permission settings.inventory.

Request body

mode: "off" | "built_in" | "automation"
off · built_in (PropZolo pings owners) · automation (workflows ask, on property.reconfirm_due)
ping_interval_days: integer
channel: "auto" | "whatsapp_cloud" | "sms"
max_pings_per_day: integer
stale_after_days: integer
hide_stale_from_matching: boolean
hide_stale_from_shares: boolean
notify_agent: boolean
price_nudge_days: integer
0 = no price-revision nudges.
price_nudge_max_enquiries: integer
mandate_notice: boolean
Emit property.mandate_expiring for the mandate-renewal recipe.

Response · 200

datarequired: ListingFreshnessSettings
metarequired: object

Request

curl -X PATCH 'https://api.propzolo.com/v1/listing-freshness/settings' \
  -H 'Authorization: Bearer pz_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"off","ping_interval_days":7,"channel":"auto","max_pings_per_day":1,"stale_after_days":7,"hide_stale_from_matching":true,"hide_stale_from_shares":true,"notify_agent":true,"price_nudge_days":0,"price_nudge_max_enquiries":0,"mandate_notice":true}'

Response example

{
  "data": {
    "mode": "off",
    "ping_interval_days": 7,
    "channel": "auto",
    "max_pings_per_day": 1,
    "stale_after_days": 7,
    "hide_stale_from_matching": true,
    "hide_stale_from_shares": true,
    "notify_agent": true,
    "price_nudge_days": 0,
    "price_nudge_max_enquiries": 0,
    "mandate_notice": true
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
409 A unique value already exists, a concurrent change won, or the Idempotency-Key is still in use or was sent with a different request.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

POST/v1/properties/{id}/freshness/confirm

Mark availability confirmed with the owner

After a call: the listing is fresh again (and no longer stale).

Access: API key with properties:write, or a member session. Permission properties.edit.

Parameters

idpathrequired: Id
Opaque record id.

Response · 200

datarequired: object
data.idrequired: Id
Opaque record id.
data.verified_atrequired: DateTime
Instant in ISO 8601, e.g. 2026-10-03T04:30:00.000Z.
metarequired: object

Request

curl -X POST 'https://api.propzolo.com/v1/properties/{id}/freshness/confirm' \
  -H 'Authorization: Bearer pz_live_…'

Response example

{
  "data": {
    "id": "cmusrceel0000q7kaafxqi1om",
    "verified_at": "2026-10-06T05:30:00.000Z"
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
404 Not found — records of another company are reported the same way.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

POST/v1/properties/{id}/freshness/ping

Ask the owner to confirm availability now

Sends the tracked “still available?” link through the messaging pipeline (compliance gates apply).

Access: API key with properties:write, or a member session. Permission properties.edit.

Parameters

idpathrequired: Id
Opaque record id.

Response · 200

datarequired: OwnerPingResult
metarequired: object

Request

curl -X POST 'https://api.propzolo.com/v1/properties/{id}/freshness/ping' \
  -H 'Authorization: Bearer pz_live_…'

Response example

{
  "data": {
    "status": "sent",
    "check_id": "cmusrceel0000q7kaafxqi1om",
    "channel": "string",
    "reason": "string"
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
404 Not found — records of another company are reported the same way.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.

{ "data": [ { "id": "cmusrceel0000q7kaafxqi1om", "ref_code": "string", "title": "string", "status": "string", "listing_type": "string", "price": 850000000, "rent_amount": 850000000, "owner": { "id": "string", "name": "string", "phone": "string" }, "has_owner": true, "listed_by": { "id": "cmusrceel0000q7kaafxqi1om", "name": "string" }, "verified_at": "2026-10-06T05:30:00.000Z", "stale_at": "2026-10-06T05:30:00.000Z", "price_nudged_at": "2026-10-06T05:30:00.000Z", "days_since_confirmed": 0, "last_check": { "id": "cmusrceel0000q7kaafxqi1om", "status": "string", "channel": "string", "blocked_reason": "string", "sent_at": "2026-10-06T05:30:00.000Z", "opened_at": "2026-10-06T05:30:00.000Z", "responded_at": "2026-10-06T05:30:00.000Z" } } ], "meta": { "next_cursor": "string", "has_more": true, "mode": "off", "stale_after_days": 0 } }

{ "data": { "mode": "off", "ping_interval_days": 7, "channel": "auto", "max_pings_per_day": 1, "stale_after_days": 7, "hide_stale_from_matching": true, "hide_stale_from_shares": true, "notify_agent": true, "price_nudge_days": 0, "price_nudge_max_enquiries": 0, "mandate_notice": true }, "meta": {} }

curl -X PATCH 'https://api.propzolo.com/v1/listing-freshness/settings' \ -H 'Authorization: Bearer pz_live_…' \ -H 'Content-Type: application/json' \ -d '{"mode":"off","ping_interval_days":7,"channel":"auto","max_pings_per_day":1,"stale_after_days":7,"hide_stale_from_matching":true,"hide_stale_from_shares":true,"notify_agent":true,"price_nudge_days":0,"price_nudge_max_enquiries":0,"mandate_notice":true}'

POST/v1/properties/{id}/freshness/confirm

Mark availability confirmed with the owner

After a call: the listing is fresh again (and no longer stale).

Access: API key with properties:write, or a member session. Permission properties.edit.

Parameters

idpathrequired: Id
Opaque record id.

Response · 200

datarequired: object
data.idrequired: Id
Opaque record id.
data.verified_atrequired: DateTime
Instant in ISO 8601, e.g. 2026-10-03T04:30:00.000Z.
metarequired: object

Request

curl -X POST 'https://api.propzolo.com/v1/properties/{id}/freshness/confirm' \
  -H 'Authorization: Bearer pz_live_…'

Response example

{
  "data": {
    "id": "cmusrceel0000q7kaafxqi1om",
    "verified_at": "2026-10-06T05:30:00.000Z"
  },
  "meta": {}
}

Errors

401 No valid session or API key (missing, expired or revoked).
403 The caller lacks the permission, API-key scope or support grant this operation needs.
404 Not found — records of another company are reported the same way.
422 Invalid input; `error.fields` maps field paths to messages.
429 Too many requests; retry after the Retry-After header.
500 Unexpected error; quote `error.request_id` to support.