> ## 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. # List saved searches > Returns every saved search of the lead, including its conditions and alert delivery settings. Returns an empty collection when the lead has none. ## OpenAPI ````yaml openapi/openapi.json GET /v1.0/leads/{leadId}/savedSearches 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. paths: /v1.0/leads/{leadId}/savedSearches: get: tags: - Saved Searches summary: List the saved searches of a lead description: >- Returns every saved search of the lead, including its conditions and alert delivery settings. Returns an empty collection when the lead has none. operationId: listSavedSearches parameters: - name: leadId in: path required: true schema: type: integer format: int64 - name: source in: query description: >- Comma separated origins to keep: AGENT_CREATED, LEAD_CREATED, SYSTEM_CREATED. Defaults to all. System-created searches are usually excluded when migrating, because the target system generates its own and importing ours would duplicate the alerts. required: false schema: type: string example: AGENT_CREATED,LEAD_CREATED - name: includeInactive in: query description: >- Include searches whose alerts are switched off. Note that an INSTANTLY cadence is active, not off. required: false schema: type: boolean default: false - name: Authorization in: header description: Bearer [access_token] required: true schema: type: string responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/SavedSearch' '400': description: Invalid source value '403': description: The token user cannot access this lead components: schemas: 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 saleType: type: string description: Which side of the transaction the search was built for enum: - SELLER - BUYER 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 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' createdAt: type: string description: Creation time, ISO 8601 UTC example: '2025-11-02T18:22:31Z' updatedAt: type: string description: Last update time, ISO 8601 UTC example: '2026-07-14T09:05:12Z' 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 SavedSearchCriteria: type: object properties: locations: $ref: '#/components/schemas/SavedSearchLocations' priceMin: type: integer description: Minimum list price format: int64 example: 350000 priceMax: type: integer description: Maximum list price format: int64 example: 600000 soldPriceMin: type: integer description: Minimum sold price; seller-side searches only format: int64 soldPriceMax: type: integer description: Maximum sold price; seller-side searches only format: int64 bedsMin: type: integer description: Minimum bedrooms format: int32 example: 3 bedsMax: type: integer description: Maximum bedrooms format: int32 bathsMin: type: number description: Minimum bathrooms format: double example: 2 bathsMax: type: number description: Maximum bathrooms format: double sqftMin: type: integer description: Minimum living area in square feet format: int32 sqftMax: type: integer description: Maximum living area in square feet format: int32 lotSizeMin: type: number description: Minimum lot size, in the unit the source MLS uses format: double lotSizeMax: type: number description: Maximum lot size, in the unit the source MLS uses format: double yearBuiltMin: type: integer description: Earliest year built format: int32 yearBuiltMax: type: integer description: Latest year built format: int32 daysOnSite: type: integer description: Only listings added within this many days format: int32 example: 7 daysSold: type: integer description: Only listings sold within this many days; seller-side searches only format: int32 example: 45 listingType: type: string description: Listing type filter as stored by the source site example: all-listing propertyTypes: type: array description: Property types example: - Single Family Residence items: type: string propertySubTypes: type: array description: Property sub types items: type: string listingStatuses: type: array description: Listing statuses example: - Active - Coming Soon items: type: string purchaseTypes: type: array description: Whether the search targets for-sale or for-rent listings items: type: string enum: - FOR_SALE - FOR_RENT keywords: type: array description: Free-text keywords items: type: string includeOpenHouse: type: boolean description: Whether open-house listings are included description: The search filters 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) 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 items: $ref: '#/components/schemas/GeoPoint' mapCircles: type: array description: >- Circles of a radius-based search; empty when the search is not radius-based items: $ref: '#/components/schemas/MapCircle' description: Where the search looks GeoPoint: type: object properties: lat: type: number description: Latitude format: double example: 37.97717892480743 lng: type: number description: Longitude format: double example: -122.11879621484377 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 format: double example: 3 unit: type: string description: Unit the radius is expressed in example: miles description: >- Circles of a radius-based search; empty when the search is not radius-based ````