> ## Documentation Index > Fetch the complete documentation index at: https://developer.lofty.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml openapi/openapi.json PUT /v1.0/leads/{leadId}/savedSearches/{savedSearchId} openapi: 3.0.1 info: title: Lofty Service Open APIs description: Lofty service API description version: '1.0' servers: - url: https://api.lofty.com security: [] tags: - name: Tasks & Appointments V2 description: >- Unified V2 API for lead tasks and appointments: list, create, read, update, finish, unfinish and delete. Tasks and appointments share the same taskId namespace; each endpoint resolves the target by ID regardless of underlying type. - name: Opportunity description: Operations about opportunity - name: Communication V2 description: >- Fetch a single communication record (text / email / call) by its communication ID. Closes the webhook follow-up gap where only list-by-lead endpoints existed for text and email. - name: Vendor description: >- Team vendor directory: team members, sub-accounts and associated agents within the caller's team. - name: Lead Routing description: >- Lead routing configuration: read and update routing rules and default (supplement) rules per business type, and list the members and roles available for assignment. - name: Lead Activity V2 API description: >- Unified lead activity timeline: returns call, text and email activities for a lead in chronological order, including both auto-captured and agent-logged entries. - name: Tasks & Appointments description: >- Agent tasks and lead appointments. Supports listing a lead's appointments, listing / reading / creating / updating / deleting tasks on a lead. - name: Transactions V2 description: V2 transaction APIs. - name: Lead Manual Log description: >- Agent-recorded log of communications that happened outside the Lofty CRM (calls placed on a personal line, emails sent from another mailbox, SMS sent from another device). Three channels are supported: logCall, logEmail, logText. Direction fields are recorded from the agent's point of view: 'outbound' = agent -> lead, 'inbound' = lead -> agent. Persistence is asynchronous: a POST returns the new entry's ID once the write is enqueued, and the entry becomes readable after a short delay. - name: Calls description: >- Calls placed or received through the Lofty dialer. Supports fetching a recording URL, retrieving a single call record, and listing calls attached to a lead. - name: Agents V2 description: >- Agent lifecycle management: deactivate an agent of the caller's team (frees the license seat, revokes sessions and tokens, keeps leads and data untouched) and reactivate a previously deactivated agent (re-occupies a seat and restores access without data loss). Deactivation is reversible and distinct from deletion. - name: Agent User description: >- Agent onboarding and team directory operations. Create a new agent under the caller's team and attach tags to existing agents. - name: Sales Agents V2 description: >- Sales Agent (AI Assistant) management: read the caller's assistant and quota, query leads followed by AI, mute leads, manage working-pool membership and plan tasks, and update Sales Agent settings. - name: Calendar V2 API description: >- Unified V2 API for tasks and appointments on a lead: create, update, delete, finish, unfinish, query a paginated list, and find available meeting slots. Calendar IDs returned by POST /v2.0/calendar are composite strings of the form '``-task' or '``-appointment' and must be sent back as-is to the per-entry endpoints. - name: Lead System Logs description: Query a lead's system log. - name: Lead Transaction description: Operations about leads - name: Notifications V2 description: Operations for sending notifications to agents - name: Notes description: >- Free-text notes attached to a lead. Supports create, list, get-by-id, update and delete. Notes may be pinned to surface them at the top of the lead's timeline. System-generated notes (automated activity) are included on the list endpoint only when explicitly requested. - name: Listing description: >- Listing data access: retrieve published listings for a site feed (XML), and search active / sold listings by agent, office or MLS id. - name: Intelligent Features description: AI-powered features for lead analysis and communication - name: Leads description: >- Lead lifecycle operations: create / read / update / delete a lead, search leads by stage, source, tag, create time or update time, place an inquiry or property on a lead, list lead activities, resolve assignee by lead info, and handle Brokermint contact callbacks. - name: Members description: >- Team member directory: look up members by user ID, by account (email), or list all members of the caller's team. Also supports retrieving the current user's profile. - name: Team Features description: >- Team-scoped metadata: lead tags, custom fields, and lead ponds. Supports listing existing entries, adding a new custom field, and retrieving a specific lead pond. - name: Agent Organization description: >- Team organizational structure: read the caller's organization info, manage company and office records, and list permission profiles available to the team. - name: Communication description: >- Lead communication history and outbound messaging: list call / email / text history for a lead, search communications for an agent, and send SMS or email to a lead. - name: Webhooks description: > Use webhooks to be notified about events that happen in a lofty account. Supported webhook event types (listId): | listId | Event Type | Description | |--------|-----------|-------------| | 1 | Agent Info | Agent created or updated | | 2 | Lead Info | Lead created, updated, or deleted | | 3 | Lead Activity | Lead site activity (e.g. SiteBrowse, SiteFavorite, SiteSearch) | | 4 | Listing Alert | Listing alert changed | | 5 | Transaction | Transaction created, updated, or deleted | | 6 | Call | Call event (MANUAL and LOGGED only, excludes AUTO) | | 7 | Email | Email event (MANUAL and LOGGED only, excludes AUTO) | | 8 | Text | Text message event (MANUAL and LOGGED only, excludes AUTO) | | 9 | Note | Note created, updated, or deleted | | 10 | Task | Task created, updated, finished, or deleted | | 11 | Appointment | Appointment created, updated, finished, or deleted | | 12 | Pipeline Change | Lead pipeline stage changed | ### Notification Recipient Rules Here "team" means the entire Lofty client account (the organization), not the Lofty "Team add-on" product. Which subscribed users receive a callback depends on the subscription's delivery mode (`permissionMode`). In both modes, only users in the lead's account (team) who have subscribed to the event type are considered. **Assignment-based delivery — `permissionMode: 0` (default)** A subscriber receives the callback only for leads assigned to them or that they administer: - If the lead is a **hidden lead**, only the **assigned agent** receives the notification. - Otherwise, the subscriber receives it if they are the **assigned agent** of the lead, or a **Company Owner** or **Company Admin**. - All other subscribers do **not** receive the notification. **Ownership-based delivery — `permissionMode: 1`** A subscriber receives the callback for any lead they manage, regardless of who it is assigned to: - Every assignment-based case above still applies (assigned agent, Company Owner / Company Admin). - In addition, the subscriber receives the callback for any lead within their **ownership scope** — a lead owned by their **team** or **office**, or **personally owned** by them — even if it is assigned to someone else. - Hidden leads are still delivered only to users who manage them. Ownership-based mode is intended for team/account-level integrations that must cover every lead in their scope, not only assigned leads. Set `permissionMode` when creating the subscription (POST /v1.0/webhook); it defaults to `0`, so existing subscriptions are unaffected. ### Delivery Timing Webhooks are typically delivered within **1 minute** of the event being triggered. During periods of high traffic, delivery may be delayed, but will always be sent within **5 minutes**. For detailed callback payload structures, see [Webhook Event Payloads](/concepts/webhooks#event-payloads). - name: Saved Searches description: >- Read the property searches a lead has saved, together with how their listing alerts are delivered. A saved search and its listing alert are one object: the search conditions and the delivery cadence travel together. ### Coverage `criteria` is a fixed field set. Filters this version does not model yet are listed by name in `unmappedCriteria`, so a partially understood search can be told apart from a fully mapped one. Values of unmapped filters are not returned. ### Pausing alerts A paused search keeps its conditions and schedule; only the emails stop. Pausing sets the cadence to NEVER, the same as choosing Never in the CRM, so a paused search reads back as `INACTIVE`, with the cadence it replaced in `frequencyBeforePause`; resume restores the same cadence. Alerts also stay silent while the lead is unsubscribed from property alerts, whatever the cadence. ### Errors A request rejected by validation or by a business rule (missing or invalid field, duplicate search, recipient that is not the lead's, ...) answers HTTP 200 with `{"code": , "message": "..."}` instead of the saved search. Check `code` in the body rather than the HTTP status. Unknown ids answer HTTP 404 and leads the token user cannot see answer HTTP 403. | code | meaning | |---|---| | 20012 | A field is missing, invalid or not allowed; `message` names it | | 2000001 | A saved search of the lead already has the same filters | | 2000005 | The lead has no email address to send alerts to | | 2000011 | The saved search cannot be edited (created by the lead on the website) | | 100000 | Lofty could not complete the change; try again later | paths: /v1.0/leads/{leadId}/savedSearches/{savedSearchId}: put: tags: - Saved Searches summary: Update a lead's existing property alert or market snapshot description: >- 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. operationId: updateSavedSearch parameters: - name: leadId in: path description: ID of the lead the saved search belongs to. required: true schema: minimum: 1 type: integer format: int64 example: 100001 - name: savedSearchId in: path description: ID of the saved search to update. required: true schema: minimum: 1 type: integer format: int64 example: 88123456789 - name: Authorization in: header description: Bearer [access_token] required: true schema: type: string - name: Content-Type in: header description: application/json required: true schema: type: string example: application/json requestBody: content: application/json: schema: $ref: '#/components/schemas/SavedSearchWriteRequest' examples: changeFilters: summary: Rename and change the filters; other fields stay as they are description: changeFilters value: name: San Jose 3BR under 1.3M criteria: locations: cities: - San Jose, CA - Campbell, CA priceMax: 1300000 bedsMin: 3 changeFrequency: summary: Only change how often the emails go out description: changeFrequency value: alertFrequency: WEEKLY schedule: FRI: AM required: true responses: '200': description: >- Success. A request rejected by validation or by a business rule also answers HTTP 200, with `{"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. content: application/json: schema: $ref: '#/components/schemas/SavedSearchResponse' '403': description: The token user cannot access this lead '404': description: The saved search is not one of this lead's components: schemas: SavedSearchWriteRequest: type: object properties: category: type: string description: >- Which emails the search sends. Required on create, cannot be changed on update. example: PROPERTY_ALERT enum: - PROPERTY_ALERT - MARKET_SNAPSHOT name: maxLength: 255 type: string description: >- 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. example: Cary 3BR under 600k alertFrequency: type: string description: >- 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. example: DAILY enum: - INSTANTLY - DAILY - WEEKLY - BIWEEKLY - MONTHLY - NEVER schedule: type: object properties: SUN: type: string enum: - AM - PM MON: type: string enum: - AM - PM TUE: type: string enum: - AM - PM WED: type: string enum: - AM - PM THU: type: string enum: - AM - PM FRI: type: string enum: - AM - PM SAT: type: string enum: - AM - PM description: >- 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). example: MON: AM THU: AM criteria: $ref: '#/components/schemas/SavedSearchCriteria' recipientEmails: type: array description: >- 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. items: type: string example: jane@example.com emailSubject: maxLength: 255 type: string description: >- Subject line of the alert emails, up to 255 characters; blank uses the default subject sendCopyToAgent: type: boolean description: >- Whether the assigned agent gets a copy of every alert email. Defaults on create to true. sendFirstEmailNow: type: boolean description: >- 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). SavedSearchResponse: type: object properties: savedSearch: $ref: '#/components/schemas/SavedSearch' SavedSearchCriteria: type: object properties: locations: $ref: '#/components/schemas/SavedSearchLocations' priceMin: type: integer description: 'Minimum list price. When writing: PROPERTY_ALERT only' format: int64 example: 350000 nullable: true priceMax: type: integer description: 'Maximum list price. When writing: PROPERTY_ALERT only' format: int64 example: 600000 nullable: true soldPriceMin: type: integer description: 'Minimum sold price. When writing: MARKET_SNAPSHOT only' format: int64 nullable: true soldPriceMax: type: integer description: 'Maximum sold price. When writing: MARKET_SNAPSHOT only' format: int64 nullable: true bedsMin: type: integer description: Minimum bedrooms format: int32 example: 3 nullable: true bedsMax: type: integer description: Maximum bedrooms format: int32 nullable: true bathsMin: type: number description: Minimum bathrooms format: double example: 2 nullable: true bathsMax: type: number description: Maximum bathrooms format: double nullable: true sqftMin: type: integer description: Minimum living area in square feet format: int32 nullable: true sqftMax: type: integer description: Maximum living area in square feet format: int32 nullable: true lotSizeMin: type: number description: Minimum lot size in square feet (one acre is 43560) format: double nullable: true lotSizeMax: type: number description: Maximum lot size in square feet (one acre is 43560) format: double nullable: true yearBuiltMin: type: integer description: Earliest year built format: int32 nullable: true yearBuiltMax: type: integer description: Latest year built format: int32 nullable: true daysOnSite: type: integer description: >- Only listings added within this many days. When writing: PROPERTY_ALERT only, above 0 format: int32 example: 7 nullable: true daysSold: type: integer description: >- Only listings sold within this many days. When writing: MARKET_SNAPSHOT only, above 0 format: int32 example: 45 nullable: true listingType: type: string description: Listing type filter as stored by the source site. Read only example: all-listing nullable: true propertyTypes: type: array description: >- Property types. When writing: values must match the options Lofty shows for the lead's site exactly, including letter case. A value that is not an option has no effect; one that differs only in case still filters but shows unselected on the CRM edit page items: type: string example: Single Family Residence propertySubTypes: type: array description: >- Property sub types. When writing: values must match the options Lofty shows for the lead's site exactly, including letter case. A value that is not an option has no effect; one that differs only in case still filters but shows unselected on the CRM edit page items: type: string listingStatuses: type: array description: >- Listing statuses. When writing: values must match the options Lofty shows for the lead's site exactly, including letter case. A value that is not an option has no effect; one that differs only in case still filters but shows unselected on the CRM edit page. Omitted means Active for a PROPERTY_ALERT and Sold for a MARKET_SNAPSHOT, whose list must include Sold items: type: string example: Active purchaseTypes: type: array description: >- Whether the search targets for-sale or for-rent listings. When writing: PROPERTY_ALERT only; omitted means FOR_SALE items: type: string enum: - FOR_SALE - FOR_RENT keywords: type: array description: Free-text keywords items: type: string includeOpenHouse: type: boolean description: >- When true, only listings with an open house are matched. When writing: PROPERTY_ALERT only nullable: true description: >- 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. SavedSearch: type: object properties: id: type: integer description: Saved search id format: int64 example: 88123456789 leadId: type: integer description: Id of the lead this search belongs to format: int64 example: 651095960136641 name: type: string description: Name given to the search example: Cary 3BR under 600k source: type: string description: Who created the search enum: - AGENT_CREATED - LEAD_CREATED - SYSTEM_CREATED nullable: true saleType: type: string description: Which side of the transaction the search was built for enum: - SELLER - BUYER nullable: true status: type: string description: ACTIVE unless alerts have been switched off for this search enum: - ACTIVE - INACTIVE alertFrequency: type: string description: >- Delivery cadence. INSTANTLY means real time, not disabled. NEVER means paused - by this API, by an agent or the lead, or automatically by Lofty after a long run of unopened emails; the search is kept and can be switched back on. TERMINATED and REFUSED are switched-off states left by older Lofty features: no email is sent, they can appear when reading but cannot be written. enum: - NEVER - TERMINATED - REFUSED - INSTANTLY - DAILY - WEEKLY - BIWEEKLY - MONTHLY schedule: type: object description: Delivery slots keyed by weekday, AM or PM example: MON: AM WED: AM lastSentAt: type: string description: When the last alert email went out, ISO 8601 UTC example: '2026-08-25T13:00:00Z' nullable: true createdAt: type: string description: Creation time, ISO 8601 UTC example: '2025-11-02T18:22:31Z' nullable: true updatedAt: type: string description: Last update time, ISO 8601 UTC example: '2026-07-14T09:05:12Z' nullable: true criteria: $ref: '#/components/schemas/SavedSearchCriteria' unmappedCriteria: type: array description: >- Names of filters this API version does not model yet. Names only: the values are withheld because the underlying storage mixes in data that is not search intent. Use it to tell a partially understood search from a fully mapped one items: type: string hasUnmappedCriteria: type: boolean description: Whether unmappedCriteria is non-empty category: type: string description: >- Which emails this search sends: PROPERTY_ALERT for buyer searches, MARKET_SNAPSHOT for seller searches enum: - PROPERTY_ALERT - MARKET_SNAPSHOT frequencyBeforePause: type: string description: >- For an INACTIVE search, the cadence it ran at before it was switched off - what the resume endpoint restores. Null while active or when unknown nullable: true enum: - NEVER - TERMINATED - REFUSED - INSTANTLY - DAILY - WEEKLY - BIWEEKLY - MONTHLY recipientEmails: type: array description: >- Email addresses receiving the alerts. Empty means the lead's main email address items: type: string example: jane@example.com emailSubject: type: string description: Subject line of the alert emails; blank means the default subject nullable: true sendCopyToAgent: type: boolean description: Whether the assigned agent gets a copy of every alert email nullable: true description: The lead's saved searches SavedSearchLocations: type: object properties: cities: type: array description: Cities items: type: string zipCodes: type: array description: Zip codes items: type: string excludedZipCodes: type: array description: Zip codes explicitly excluded from the search items: type: string counties: type: array description: Counties items: type: string neighborhoods: type: array description: Neighborhoods, merging MLS-sourced and Lofty-maintained ones items: type: string subdivisions: type: array description: Subdivisions items: type: string communities: type: array description: Communities items: type: string areas: type: array description: MLS areas items: type: string schoolDistricts: type: array description: School districts items: type: string schools: type: array description: >- Named schools (elementary, middle and high combined). Read only: to write schools use elementarySchools, middleSchools and highSchools items: type: string streetNames: type: array description: Street names items: type: string states: type: array description: States items: type: string mapPath: type: array description: >- Vertices of a map-drawn search polygon; empty when the search is not map-drawn. When writing: 3 to 500 points, and not together with named locations items: $ref: '#/components/schemas/GeoPoint' mapCircles: type: array description: >- Circles of a radius-based search; empty when the search is not radius-based. When writing: not together with named locations items: $ref: '#/components/schemas/MapCircle' elementarySchools: type: array description: Elementary schools items: type: string middleSchools: type: array description: Middle schools items: type: string highSchools: type: array description: High schools items: type: string description: >- Where the search looks. When writing: optional - omit it or send an empty object for a search without a location filter. Named locations (cities, zipCodes, counties, neighborhoods, subdivisions, communities, areas, schoolDistricts, elementarySchools, middleSchools, highSchools) and drawn ones (mapCircles, mapPath) cannot be used together. GeoPoint: type: object properties: lat: type: number description: Latitude, -90 to 90 format: double example: 37.97717892480743 maximum: 90 minimum: -90 lng: type: number description: Longitude, -180 to 180 format: double example: -122.11879621484377 maximum: 180 minimum: -180 description: Centre of the search circle MapCircle: type: object properties: center: $ref: '#/components/schemas/GeoPoint' radius: type: number description: >- Radius, in the unit given by unit. Must be positive; when writing, at most 100 miles or 160 kilometers format: double example: 3 unit: type: string description: >- Unit the radius is expressed in: miles or kilometers, in any letter case and stored lower case. Optional when writing - omitted or blank means miles. Any other value is rejected example: miles enum: - miles - kilometers description: >- Circles of a radius-based search; empty when the search is not radius-based. When writing: not together with named locations ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.