Saved Searches

Update saved search

Changes the locations, price range, bedrooms, email frequency, schedule or recipients of an existing property alert or market snapshot (saved search) in place. Only the fields sent are changed; omitted fields keep their values. criteria, when sent, replaces every filter the API can write, and filters it cannot write are kept. A paused search stays paused unless alertFrequency is sent. Searches the lead created on the website cannot be edited. Returns the search as stored.

name, when sent, must be 1-255 characters.

The rules of each filter are on the criteria fields; how schedule follows a changed alertFrequency is on the schedule field.

PUT

v1.0

leads

{leadId}

savedSearches

{savedSearchId}

curl --request PUT \
  --url https://api.lofty.com/v1.0/leads/{leadId}/savedSearches/{savedSearchId} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "San Jose 3BR under 1.3M",
  "criteria": {
    "locations": {
      "cities": [
        "San Jose, CA",
        "Campbell, CA"
      ]
    },
    "priceMax": 1300000,
    "bedsMin": 3
  }
}
'

{
  "savedSearch": {
    "id": 88123456789,
    "leadId": 651095960136641,
    "name": "Cary 3BR under 600k",
    "source": "AGENT_CREATED",
    "saleType": "SELLER",
    "status": "ACTIVE",
    "alertFrequency": "NEVER",
    "schedule": {
      "MON": "AM",
      "WED": "AM"
    },
    "lastSentAt": "2026-08-25T13:00:00Z",
    "createdAt": "2025-11-02T18:22:31Z",
    "updatedAt": "2026-07-14T09:05:12Z",
    "criteria": {
      "locations": {
        "cities": [
          "<string>"
        ],
        "zipCodes": [
          "<string>"
        ],
        "excludedZipCodes": [
          "<string>"
        ],
        "counties": [
          "<string>"
        ],
        "neighborhoods": [
          "<string>"
        ],
        "subdivisions": [
          "<string>"
        ],
        "communities": [
          "<string>"
        ],
        "areas": [
          "<string>"
        ],
        "schoolDistricts": [
          "<string>"
        ],
        "schools": [
          "<string>"
        ],
        "streetNames": [
          "<string>"
        ],
        "states": [
          "<string>"
        ],
        "mapPath": [
          {
            "lat": 37.97717892480743,
            "lng": -122.11879621484377
          }
        ],
        "mapCircles": [
          {
            "center": {
              "lat": 37.97717892480743,
              "lng": -122.11879621484377
            },
            "radius": 3,
            "unit": "miles"
          }
        ],
        "elementarySchools": [
          "<string>"
        ],
        "middleSchools": [
          "<string>"
        ],
        "highSchools": [
          "<string>"
        ]
      },
      "priceMin": 350000,
      "priceMax": 600000,
      "soldPriceMin": 123,
      "soldPriceMax": 123,
      "bedsMin": 3,
      "bedsMax": 123,
      "bathsMin": 2,
      "bathsMax": 123,
      "sqftMin": 123,
      "sqftMax": 123,
      "lotSizeMin": 123,
      "lotSizeMax": 123,
      "yearBuiltMin": 123,
      "yearBuiltMax": 123,
      "daysOnSite": 7,
      "daysSold": 45,
      "listingType": "all-listing",
      "propertyTypes": [
        "Single Family Residence"
      ],
      "propertySubTypes": [
        "<string>"
      ],
      "listingStatuses": [
        "Active"
      ],
      "purchaseTypes": [
        "FOR_SALE"
      ],
      "keywords": [
        "<string>"
      ],
      "includeOpenHouse": true
    },
    "unmappedCriteria": [
      "<string>"
    ],
    "hasUnmappedCriteria": true,
    "category": "PROPERTY_ALERT",
    "frequencyBeforePause": "NEVER",
    "recipientEmails": [
      "jane@example.com"
    ],
    "emailSubject": "<string>",
    "sendCopyToAgent": true
  }
}

Headers

Authorization

string

required

Bearer [access_token]

Content-Type

string

required

application/json

Path Parameters

leadId

integer<int64>

required

ID of the lead the saved search belongs to.

Required range: x >= 1

savedSearchId

integer<int64>

required

ID of the saved search to update.

Required range: x >= 1

Body

application/json

category

enum<string>

Which emails the search sends. Required on create, cannot be changed on update.

Available options:

PROPERTY_ALERT,

MARKET_SNAPSHOT

Example:

"PROPERTY_ALERT"

name

string

Name given to the search, up to 255 characters. Required and not blank on create; on update it may be omitted but not sent blank.

Maximum string length: 255

Example:

"Cary 3BR under 600k"

alertFrequency

enum<string>

Delivery cadence: INSTANTLY, DAILY, WEEKLY, BIWEEKLY, MONTHLY, or NEVER to keep the search paused. Required on create. Setting NEVER on update works like the pause endpoint and keeps the schedule, so resume can switch it back on. A search created with NEVER had no earlier cadence: switch it on by setting alertFrequency here.

Available options:

INSTANTLY,

DAILY,

WEEKLY,

BIWEEKLY,

MONTHLY,

NEVER

Example:

"DAILY"

schedule

object

Delivery slots keyed by weekday (SUN to SAT), AM or PM, in the team owner's time zone. DAILY takes one or more days; WEEKLY, BIWEEKLY and MONTHLY take exactly one; INSTANTLY takes none. When omitted on create, Lofty picks the slots: every day for DAILY, the current day for WEEKLY, BIWEEKLY and MONTHLY. When omitted on an update that changes alertFrequency, the slots follow the new cadence: NEVER keeps them for a later resume, INSTANTLY clears them, DAILY keeps the days (Monday and Thursday morning if there were none), and WEEKLY, BIWEEKLY and MONTHLY keep the earliest day of the week (Monday morning if there were none).

Show child attributes

Example:

{ "MON": "AM", "THU": "AM" }

criteria

object

Filters of a saved search. Shared by reads and writes; rules marked "When writing" apply to create and update only. On update, sending criteria replaces every writable filter at once.

Show child attributes

recipientEmails

string[]

Email addresses of the lead (or the lead's family members) who receive the alerts. Each must be one of the lead's own email addresses. Defaults on create to the lead's primary email.

emailSubject

string

Subject line of the alert emails, up to 255 characters; blank uses the default subject

Maximum string length: 255

sendCopyToAgent

boolean

Whether the assigned agent gets a copy of every alert email. Defaults on create to true.

sendFirstEmailNow

boolean

Send the first alert email right away instead of waiting for the schedule. Defaults to true when creating a PROPERTY_ALERT, false otherwise; must not be true while the search is paused (NEVER).

Response

Success. A request rejected by validation or by a business rule also answers HTTP 200, with {"code": <error code>, "message": "..."} in place of the result: check code in the body, not the HTTP status. Codes are listed under Errors in the Saved Searches section.

savedSearch

object

The lead's saved searches

Show child attributes

curl --request PUT \
  --url https://api.lofty.com/v1.0/leads/{leadId}/savedSearches/{savedSearchId} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "San Jose 3BR under 1.3M",
  "criteria": {
    "locations": {
      "cities": [
        "San Jose, CA",
        "Campbell, CA"
      ]
    },
    "priceMax": 1300000,
    "bedsMin": 3
  }
}
'

{
  "savedSearch": {
    "id": 88123456789,
    "leadId": 651095960136641,
    "name": "Cary 3BR under 600k",
    "source": "AGENT_CREATED",
    "saleType": "SELLER",
    "status": "ACTIVE",
    "alertFrequency": "NEVER",
    "schedule": {
      "MON": "AM",
      "WED": "AM"
    },
    "lastSentAt": "2026-08-25T13:00:00Z",
    "createdAt": "2025-11-02T18:22:31Z",
    "updatedAt": "2026-07-14T09:05:12Z",
    "criteria": {
      "locations": {
        "cities": [
          "<string>"
        ],
        "zipCodes": [
          "<string>"
        ],
        "excludedZipCodes": [
          "<string>"
        ],
        "counties": [
          "<string>"
        ],
        "neighborhoods": [
          "<string>"
        ],
        "subdivisions": [
          "<string>"
        ],
        "communities": [
          "<string>"
        ],
        "areas": [
          "<string>"
        ],
        "schoolDistricts": [
          "<string>"
        ],
        "schools": [
          "<string>"
        ],
        "streetNames": [
          "<string>"
        ],
        "states": [
          "<string>"
        ],
        "mapPath": [
          {
            "lat": 37.97717892480743,
            "lng": -122.11879621484377
          }
        ],
        "mapCircles": [
          {
            "center": {
              "lat": 37.97717892480743,
              "lng": -122.11879621484377
            },
            "radius": 3,
            "unit": "miles"
          }
        ],
        "elementarySchools": [
          "<string>"
        ],
        "middleSchools": [
          "<string>"
        ],
        "highSchools": [
          "<string>"
        ]
      },
      "priceMin": 350000,
      "priceMax": 600000,
      "soldPriceMin": 123,
      "soldPriceMax": 123,
      "bedsMin": 3,
      "bedsMax": 123,
      "bathsMin": 2,
      "bathsMax": 123,
      "sqftMin": 123,
      "sqftMax": 123,
      "lotSizeMin": 123,
      "lotSizeMax": 123,
      "yearBuiltMin": 123,
      "yearBuiltMax": 123,
      "daysOnSite": 7,
      "daysSold": 45,
      "listingType": "all-listing",
      "propertyTypes": [
        "Single Family Residence"
      ],
      "propertySubTypes": [
        "<string>"
      ],
      "listingStatuses": [
        "Active"
      ],
      "purchaseTypes": [
        "FOR_SALE"
      ],
      "keywords": [
        "<string>"
      ],
      "includeOpenHouse": true
    },
    "unmappedCriteria": [
      "<string>"
    ],
    "hasUnmappedCriteria": true,
    "category": "PROPERTY_ALERT",
    "frequencyBeforePause": "NEVER",
    "recipientEmails": [
      "jane@example.com"
    ],
    "emailSubject": "<string>",
    "sendCopyToAgent": true
  }
}

Leads

Task & Calendar

Transactions

Listings

Communication

Team

AI Copilot

Webhooks

Integrations

Update saved search

Headers

Path Parameters

Body

Response