Saved Searches

Create saved search

Sets up a new property alert (category PROPERTY_ALERT) or market snapshot (category MARKET_SNAPSHOT) for the lead, with its locations, price range, bedrooms and email frequency - the same as adding a saved search in the CRM. Every field is a readable value: weekdays and AM/PM for the schedule, cadence names, email addresses for recipients. The lead needs at least one email address. A search with the same filters as an existing one of the lead is refused. Returns the search as stored.

Required: category, name (1-255 characters), alertFrequency and criteria.

The rules of each filter are on the criteria fields; schedule defaults are on the schedule field.

POST

v1.0

leads

{leadId}

savedSearches

curl --request POST \
  --url https://api.lofty.com/v1.0/leads/{leadId}/savedSearches \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "category": "PROPERTY_ALERT",
  "name": "San Jose 3BR under 1.2M",
  "alertFrequency": "DAILY",
  "schedule": {
    "MON": "AM",
    "THU": "AM"
  },
  "criteria": {
    "locations": {
      "cities": [
        "San Jose, CA"
      ]
    },
    "priceMin": 800000,
    "priceMax": 1200000,
    "bedsMin": 3,
    "bathsMin": 2,
    "propertyTypes": [
      "Single Family Home"
    ],
    "listingStatuses": [
      "Active",
      "Pending"
    ]
  },
  "sendFirstEmailNow": true
}
'

{
  "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 to create the saved search for.

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 POST \
  --url https://api.lofty.com/v1.0/leads/{leadId}/savedSearches \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "category": "PROPERTY_ALERT",
  "name": "San Jose 3BR under 1.2M",
  "alertFrequency": "DAILY",
  "schedule": {
    "MON": "AM",
    "THU": "AM"
  },
  "criteria": {
    "locations": {
      "cities": [
        "San Jose, CA"
      ]
    },
    "priceMin": 800000,
    "priceMax": 1200000,
    "bedsMin": 3,
    "bathsMin": 2,
    "propertyTypes": [
      "Single Family Home"
    ],
    "listingStatuses": [
      "Active",
      "Pending"
    ]
  },
  "sendFirstEmailNow": true
}
'

{
  "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

Create saved search

Headers

Path Parameters

Body

Response