> ## 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. # Search Listings > Search listings by location keywords and optional filters (price, bedrooms, bathrooms, sqft, property type, listing status, purchase type). ## OpenAPI ````yaml openapi/openapi.json POST /v2.0/listings/search 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: Listing V2 description: Listing search V2 - 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). paths: /v2.0/listings/search: post: tags: - Listing V2 summary: Search Listings description: >- Search listings by location keywords and optional filters (price, bedrooms, bathrooms, sqft, property type, listing status, purchase type). operationId: searchListings parameters: - 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/ListingQueryRequest' required: true responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ListingV2SearchResponse' components: schemas: ListingQueryRequest: type: object properties: searchScope: type: string description: >- Search scope. 'my' = agent's own listings, 'office' = office-level listings, 'all' = all listings the agent has access to. Default 'all'. default: all enum: - my - office - all soldFlag: type: boolean description: Whether to search sold listings. Default false (active listings). filterConditions: type: object additionalProperties: type: object description: >- Advanced search filter conditions. Keys must match condition names in the property.condition table. Examples: - "location": {"city": ["Seattle"]} (suggestion type) - "price": "100000,500000" (inputBox range: "min,max") - "beds": "2," (inputBox range: min only) - "baths": ",3" (inputBox range: max only) - "sqFt": "1000,3000" (inputBox range) - "daysOnSite": ",30" (inputBox days: within last N days) - "propertyType": ["Condo", "Townhouse"] (multiSelect labels) - "purchaseType": ["For Sale"] (singleSelect label) description: >- Advanced search filter conditions. Keys must match condition names in the property.condition table. Examples: - "location": {"city": ["Seattle"]} (suggestion type) - "price": "100000,500000" (inputBox range: "min,max") - "beds": "2," (inputBox range: min only) - "baths": ",3" (inputBox range: max only) - "sqFt": "1000,3000" (inputBox range) - "daysOnSite": ",30" (inputBox days: within last N days) - "propertyType": ["Condo", "Townhouse"] (multiSelect labels) - "purchaseType": ["For Sale"] (singleSelect label) sortFields: type: array description: >- Sort fields. Values from ListingSortEnum, e.g. MLS_LIST_DATE_L_DESC, PRICE_DESC, PRICE_ASC, BEDROOMS_DESC, BATHS_DESC, BUILT_YEAR_DESC, SQFT_DESC, RELEVANCE, QUALITY_DESC, OPEN_HOUSE_DESC. items: type: string returnFields: type: array description: Return fields. If empty, uses default fields for the listing type. items: type: string pageNum: type: integer description: Page number, starting from 1. Default 1. format: int32 default: 1 pageSize: type: integer description: Page size, 1–100. Default 25. format: int32 default: 25 ListingV2SearchResponse: type: object properties: listing: type: array items: $ref: '#/components/schemas/ListingItem' metadata: $ref: '#/components/schemas/ListingV2Metadata' description: Search response for ListingV2 ListingItem: type: object properties: listingId: type: string description: Listing ID example: '1179625482' mlsListingId: type: string description: MLS listing ID example: ML82040728 listingStreetName: type: string description: Street address example: 5164 Montreal DR listingCity: type: string description: City example: San Jose listingState: type: string description: State abbreviation example: CA listingZipcode: type: array items: type: string description: Zip code(s) county: type: string description: County name example: Santa Clara area: type: string description: Area name example: Campbell chimeArea: type: string description: Chime area name subDivisionName: type: string description: Subdivision name nullable: true community: type: string description: Community name nullable: true chimeComplex: type: string description: Chime complex nullable: true price: type: string description: Listing price example: '1950000' beds: type: number description: Number of bedrooms format: float example: 3 baths: type: number description: Number of bathrooms format: float example: 2 sqft: type: number description: Square footage format: float example: 1408 builtYear: type: integer description: Year built format: int32 example: 1959 totalAvailableAcres: type: string description: Lot size in sqft example: '6000' detailsDescribe: type: string description: Full listing description listingStatus: type: string description: Listing status example: Active purchaseType: type: string description: Purchase type example: For Sale propertyTypes: type: array items: type: string description: Property type tags propertyTypePrimary: type: string description: Primary property type example: Residential propertyTypeSecondary: type: string description: Secondary property type example: Single Family Home pictureList: type: array items: type: string description: List of photo URLs openHouseSchedules: type: string description: Open house schedule text nullable: true example: Sat Apr 04, 1:00pm - 4:00pm openHouseSchedulesStart: type: string description: Open house start datetime nullable: true example: '2026-04-04 13:00:00' openHouseSchedulesEnd: type: string description: Open house end datetime nullable: true example: '2026-04-04 16:00:00' agentId: type: string description: Listing agent ID example: '5106715' agentName: type: string description: Listing agent name example: Dawn Thorburn agentOrgId: type: string description: Listing agent org ID example: '6043409' agentOrgName: type: string description: Listing agent org name example: Rocky Properties Inc. coAgentId: type: string description: Co-agent ID nullable: true coAgentName: type: string description: Co-agent name nullable: true coAgentOrgId: type: string description: Co-agent org ID nullable: true coAgentOrgName: type: string description: Co-agent org name nullable: true hoaFee: type: number description: HOA fee (-1 if N/A) format: double example: -1 hoaFeeFrequency: type: string description: HOA fee frequency nullable: true condoFee: type: number description: Condo fee (-1 if N/A) format: double example: -1 condoFeeFrequency: type: string description: Condo fee frequency nullable: true chimeMaintenanceFee: type: number description: Chime maintenance fee format: double example: 0 garageParkingSpaces: type: number description: Number of garage/parking spaces format: double example: 2 interiorFeatures: type: string description: Interior features nullable: true exterior: type: string description: Exterior features nullable: true mlsListDateL: type: integer description: MLS list date timestamp (0 if unknown) format: int64 example: 0 description: A single listing item from MLS ListingV2Metadata: type: object properties: collection: type: string pageSize: type: integer format: int32 pageNum: type: integer format: int64 totalCount: type: integer format: int64 totalPage: type: integer format: int64 hasMore: type: boolean ````