API Documentation

By Jonathan Säther

• 7 articles

Getting Started with the API

Welcome to the LeadHQL API documentation! This guide will help you integrate LeadHQL's property listing services into your applications. Quick Start 1. Get Your API Key: Visit https://www.leadhql.com/dashboard/property-listings/settings 2. Read the Overview: Start with the API Overview documentation 3. Explore Endpoints: Check out the endpoint documentation below 4. Start Building: Use our code examples to get started quickly Documentation Structure Core Documentation - API Overview - Start here! Authentication, rate limits, and general information - Authentication Guide - How to authenticate your requests - Data Types & Enums - Reference for all property types and statuses API Endpoints Read Operations POST /properties/search Search and filter properties with natural language queries, structured filters, and geospatial search GET /properties/:id Get detailed information about a specific property GET /properties/:id/similar Find properties similar to a specific property GET /properties/stats/counts Get property statistics and counts by status Write Operations Write operations are available for managing your organization's properties. Contact support for full documentation on creating, updating, and deleting properties. Common Use Cases 1. Display Properties on Your Website 2. Build a Property Search Tool 3. Property Detail Pages with Recommendations 4. Portfolio Dashboard API Features 🔍 Powerful Search - Natural language queries - Structured filters (price, bedrooms, features) - Geospatial search (location radius or bounding box) - Full-text search across all property fields 🏷️ Rich Property Data - Comprehensive property details - Multiple images with thumbnails - Agent information - Organization branding - Ad creative data - Multilingual descriptions 📊 Analytics & Statistics - Property counts by status - Price distribution histograms - Portfolio overview metrics 🎯 Smart Recommendations - Similar property suggestions - Automatic matching based on type, location, and price - Configurable result limits 🔐 Secure & Scalable - API key authentication - Rate limiting for fair usage - Organization-scoped access control - High availability infrastructure Base URL Authentication All requests require an API key. You can provide it in three ways: Option 1: Authorization header (recommended) Option 2: X-API-Key header Option 3: Query parameter Rate Limits - 20 requests per minute - 100 requests per 10 minutes - 500 requests per hour Response Format All responses are in JSON format: Errors include: Code Examples We provide code examples in multiple languages: - JavaScript/TypeScript - For web applications and Node.js - Python - For backend services and data processing - PHP - For WordPress and traditional web applications All examples are included in the endpoint documentation. Support & Resources Getting Help - Documentation: You're reading it! Explore the links above - Support: Contact [email protected] What's Next? 1. ✅ Generate your API key 2. 📖 Read the API Overview documentation 3. 🔨 Try the Search Properties endpoint 4. 🚀 Build your integration! Feedback We're always improving our API. If you have suggestions or found an issue, please let us know: - Bug Reports: [email protected] - Feature Requests: [email protected] - General Feedback: [email protected] Happy Building! 🏗️ If you build something cool with our API, we'd love to hear about it!

Last updated on Dec 06, 2025

API Overview

LeadHQL Properties API Documentation Welcome to the LeadHQL Properties API! This API allows you to integrate property listings from LeadHQL into your own applications, websites, and services. Base URL https://api.leadhql.com Getting Started 1. Generate Your API Key 1. Navigate to https://www.leadhql.com/dashboard/property-listings/settings 2. Click the blue "Create new key" button 3. Give your API key a descriptive name (only visible to you) 4. Copy the generated API key immediately - it will only be shown once Important Notes: - Store your API key securely - If you lose your API key, you can always generate a new one - You can manage and delete unused API keys from the settings page - Each API key is scoped to your organization's properties 2. Authentication All API requests must be authenticated using your API key. You can provide your API key in one of three ways: Option 1: Authorization Header (Recommended) Option 2: X-API-Key Header Option 3: Query Parameter Available Endpoints Read Operations (Publicly Accessible) Endpoint Method Description /properties/search POST Search and filter properties /properties/:id GET Get details of a specific property /properties/:id/similar GET Find properties similar to a specific property /properties/stats/counts GET Get property counts by status /properties/:id/ad-creatives GET Get ad creatives for a property Write Operations (Organization-Scoped) Endpoint Method Description /properties POST Create a new property listing /properties/:id PUT Update an existing property /properties/:id DELETE Delete a property listing /properties/:id/renew PUT Renew a property listing (extends expiration by 2 months) /properties/expiring/soon GET Get properties expiring within a specified number of days Query Parameters Many endpoints support optional query parameters to customize the response: Parameter Type Description Default filterByOrganization boolean Filter results to only your organization's properties false includeBranding boolean Include organization branding information in response false includeAdCount boolean Include count of active ads for each property false includeAdCreatives boolean Include ad creative details (up to 3 most recent) false Example Usage Response Format All responses are returned in JSON format with the following structure: Success Response Error Response Rate Limiting The API implements rate limiting to ensure fair usage: - Short-term: 20 requests per minute - Medium-term: 100 requests per 10 minutes - Long-term: 500 requests per hour If you exceed these limits, you'll receive a 429 Too Many Requests response. Data Types and Enums Listing Status - active - Property is live and available - inactive - Property is not currently active - pending - Property is awaiting approval - sold - Property has been sold - rented - Property has been rented - deleted - Property has been deleted Listing Type - sale - Property for sale - rent - Property for rent - sale_or_rent - Property available for either Property Category - residential - Residential properties - commercial - Commercial properties - industrial - Industrial properties - land - Land plots Property Type Residential: - apartment, condominium, house_detached, house_semi_detached, house_terraced, townhouse, multi_family_home, penthouse, studio Land: - land_residential, land_commercial, land_agricultural, land_other Commercial: - office, retail, commercial_other Industrial: - industrial_warehouse, industrial_other Other: - hospitality, other Example Integration Scenarios 1. Display Your Properties on Your Website Filter by your organization and include branding to show only your listings with your company information. 2. Property Search Widget Implement a search interface that allows visitors to find properties based on location, price, bedrooms, etc. 3. Property Comparison Tool Fetch similar properties and allow users to compare features, prices, and amenities. 4. Automated Property Syndication Automatically sync your properties to multiple listing platforms. Need Help? For detailed endpoint documentation, explore: - Search Properties API - Search and filter properties - Get Property Details API - Get detailed property information - Similar Properties API - Find similar property recommendations - Property Statistics API - Get property counts and statistics For support, contact our support team through the LeadHQL dashboard.

Last updated on Dec 06, 2025

Search Properties

Search Properties API Search and filter property listings using various criteria including natural language queries, structured filters, and geospatial searches. Endpoint Authentication Required. All API requests must be authenticated using your API key. See the Authentication section in the API Overview documentation. Query Parameters Parameter Type Description Default filterByOrganization boolean Filter results to only your organization's properties false includeBranding boolean Include organization branding information false includeAdCount boolean Include count of active ads for each property false includeAdCreatives boolean Include ad creative details (max 3 most recent) false Request Body The request body supports extensive filtering options. All fields are optional. Natural Language Query The query field supports: - Natural language searches - Automatic extraction of numeric values (bedrooms, bathrooms, price) - Property features (pool, garden, terrace, etc.) - Location matching - Reference number lookup Structured Filters Property Filters Field Type Description Example query string Natural language or keyword search "luxury penthouse sea view" status string[] Filter by listing status ["active", "pending"] propertyType string[] Filter by property type ["apartment", "penthouse"] propertyCategory string[] Filter by category ["residential"] Numeric Range Filters Each range filter accepts min and/or max values: Feature Filters Geospatial Filters Option 1: Circular Radius Search Distance formats: "10km", "5mi", "2000m" Option 2: Bounding Box (Map View) Note: Bounding box takes precedence over location if both are provided. Sorting Available sort fields: price, bedrooms, bathrooms, livingArea, publishedAt, createdAt, updatedAt Pagination - page: Page number (1-indexed), default: 1 - limit: Items per page (1-100), default: 20 for list view, 1000 for map view Price Distribution Request price histogram data for filters/charts: Response Success Response (200 OK) Response Fields Conditional Fields These fields are only included based on query parameters: - agent: Included when includeAdCount=true or includeAdCreatives=true (if property has an agent) - adCount: Included when includeAdCount=true - adCreatives: Included when includeAdCreatives=true (max 3 most recent) - organizationBranding: Included when includeBranding=true - clerkOrganizationId: Included when includeBranding=true - priceDistribution: Included when priceDistribution is in request body Error Responses 401 Unauthorized 400 Bad Request Example Requests Basic Search - All Active Properties Search with Natural Language Query Advanced Filter Search Map View Search (Bounding Box) Organization's Properties with Branding Search with Price Distribution Code Examples JavaScript/TypeScript Python PHP Tips and Best Practices 1. Use Natural Language Queries: The query field is powerful and can understand natural language like "3 bedroom villa with pool under 2 million" 2. Optimize for Performance: - Only request includeBranding and includeAdCreatives when needed - Use pagination for large result sets - Use bounding box for map views (higher default limit) 3. Geospatial Search: - Bounding box is more efficient for map views - Location radius is better for "near me" searches - Distance can be specified in km, mi, or m 4. Filter by Organization: - Use filterByOrganization=true to show only your properties - Omit it (or set to false) to search all properties for public-facing listings 5. Price Distribution: - Useful for creating price range filters/sliders in your UI - The API automatically calculates appropriate intervals if not specified 6. Sorting: - Default sort is by publishedAt DESC (newest first) - Multiple sort fields are supported and applied in order

Last updated on Dec 06, 2025

Get Property Details

Get Property Details API Retrieve detailed information about a specific property by its ID. Endpoint GET /properties/:id Authentication Required. All API requests must be authenticated using your API key. See the Authentication section in the API Overview documentation. Path Parameters Parameter Type Required Description id string (UUID) Yes The unique identifier of the property Query Parameters Parameter Type Description Default filterByOrganization boolean Only return if property belongs to your organization false includeBranding boolean Include organization branding information false includeAdCount boolean Include count of active ads for the property false includeAdCreatives boolean Include ad creative details (max 3 most recent) false Response Success Response (200 OK) Returns a single property object with all details: Error Responses 404 Not Found When using filterByOrganization=true: 401 Unauthorized 400 Bad Request Example Requests Basic Request With All Optional Data Check Property Ownership Code Examples JavaScript/TypeScript Python PHP Use Cases 1. Property Detail Page Display comprehensive property information on a dedicated page: 2. Property Verification Check if a property belongs to your organization: 3. Property Comparison Fetch multiple properties for side-by-side comparison: Tips and Best Practices 1. Error Handling: Always handle 404 errors gracefully - properties may be deleted or become inactive 2. Optional Data: Only request includeBranding and includeAdCreatives when you need them to minimize response size 3. Caching: Consider caching property details on your frontend to reduce API calls 4. Deep Linking: Property IDs can be used in URLs for direct deep linking to property pages 5. Organization Filtering: Use filterByOrganization=true when you need to verify ownership before allowing edits 6. Image Display: - Use images array for full-size images in galleries - Use thumbnails array for preview/listing views - The isFeatured flag indicates the hero image 7. Agent Information: Agent data is automatically included when available and either includeAdCount or includeAdCreatives is true

Last updated on Dec 06, 2025

Similar Properties

Similar Properties API Find properties similar to a specific property based on type, location, bedrooms, and price range. Perfect for "You may also like" features and property comparison tools. Endpoint GET /properties/:id/similar Authentication Required. All API requests must be authenticated using your API key. See the Authentication section in the API Overview documentation. Path Parameters Parameter Type Required Description id string (UUID) Yes The unique identifier of the reference property Query Parameters Parameter Type Description Default limit number Maximum number of similar properties to return (1-100) 5 filterByOrganization boolean Only return properties from your organization false includeBranding boolean Include organization branding information false includeAdCount boolean Include count of active ads for each property false includeAdCreatives boolean Include ad creative details (max 3 most recent per property) false How Similarity Works The API finds similar properties using the following criteria: 1. Same Property Type - Matches exact property type (e.g., apartment, villa) 2. Same Property Category - Matches category (residential, commercial, etc.) 3. Similar Location - Same city OR same community 4. Similar Bedrooms - Within ±1 bedroom (e.g., 2-4 bedrooms for a 3-bedroom property) 5. Similar Price - Within ±25% of the reference property price 6. Active Status - Only returns active listings (by default) 7. Excludes Reference - Never returns the reference property itself Results are ordered by most recently published first. Response Success Response (200 OK) Returns an array of similar property objects: Error Responses 404 Not Found 401 Unauthorized 400 Bad Request Example Requests Basic Request (5 Similar Properties) Request More Results With Branding and Ad Information Similar Properties from Same Organization Code Examples JavaScript/TypeScript Python PHP Use Cases 1. "You May Also Like" Section Display similar properties on a property detail page: 2. Property Comparison Tool Allow users to compare similar properties: 3. Alternative Suggestions When a property becomes unavailable, suggest alternatives: 4. Cross-Selling Within Organization Show other properties from your organization: 5. Email Marketing Generate property recommendations for email campaigns: Tips and Best Practices 1. Adjust Limit Based on UI: - 3-4 for carousel displays - 6-8 for grid layouts - 10+ for list views or dedicated "similar properties" pages 2. Handle Empty Results: There may be no similar properties if: - The property is very unique - It's in a location with few other properties - The price range is extreme - Consider falling back to a broader search 3. Combine with Favorites: Show similar properties to items users have favorited 4. Performance: Similar properties queries are fast since they use indexed fields 5. Organization Filtering: Use filterByOrganization=true to: - Cross-sell within your portfolio - Avoid showing competitor properties - Keep users within your ecosystem 6. Caching: Consider caching similar properties for a few hours to reduce API calls 7. No Pagination: The similar properties endpoint returns all results up to the limit (no page parameter needed) Similarity Algorithm Details The matching criteria in priority order: 1. Must Match: - Property type (exact match) - Property category (exact match) - Status = active (unless specified otherwise) - Not the same property 2. Should Match (at least one): - Same city OR same community - Bedrooms within ±1 - Price within ±25% 3. Sorting: - Most recently published first Example Similarity Calculation For a reference property: - Type: Apartment - Category: Residential - City: Dubai - Community: Dubai Marina - Bedrooms: 3 - Price: 1,500,000 AED Similar properties will match: - Type: Apartment ✓ - Category: Residential ✓ - City: Dubai OR Community: Dubai Marina ✓ - Bedrooms: 2, 3, or 4 ✓ - Price: 1,125,000 - 1,875,000 AED ✓

Last updated on Dec 06, 2025

Property Statistics

Property Statistics API Get aggregated property counts by status for your organization. Useful for dashboards, analytics, and overview displays. Endpoint GET /properties/stats/counts Authentication Required. All API requests must be authenticated using your API key. See the Authentication section in the API Overview documentation. Query Parameters None. This endpoint automatically filters to your organization's properties based on your API key. Response Success Response (200 OK) Returns an object with property counts for each status: Response Fields Field Type Description active number Number of active (live) listings pending number Number of listings awaiting approval inactive number Number of inactive listings (expired or deactivated) sold number Number of properties marked as sold rented number Number of properties marked as rented Note: The deleted status is not included in the counts as deleted properties are excluded from statistics. All status counts default to 0 if no properties exist for that status. Error Responses 401 Unauthorized Example Requests Basic Request Code Examples JavaScript/TypeScript Python PHP Use Cases 1. Dashboard Overview Widget Display key metrics on your dashboard: 2. Portfolio Performance Chart Track your portfolio over time: 3. Status Filter Navigation Create navigation menu with counts: 4. Portfolio Health Indicator Display warnings based on statistics: 5. Performance Report Email Send weekly performance summaries: 6. Real-Time Status Badge Show live status in your application header: Tips and Best Practices 1. Caching: Cache statistics for a few minutes to reduce API calls: 2. Real-Time Updates: Poll this endpoint periodically for dashboard displays 3. Combine with Search: Use stats to show counts, then fetch actual properties: 4. Performance Metrics: Calculate derived metrics: 5. Historical Tracking: Store stats over time to: - Track growth trends - Identify seasonal patterns - Measure marketing effectiveness - Generate performance reports 6. Automated Alerts: Set up notifications: 7. Organization Comparison: If you manage multiple API keys/organizations: Response Time This endpoint is optimized with database indexes and typically responds in under 100ms. It's safe to call frequently for real-time dashboards. Limitations - Only returns counts for your organization (based on API key) - Excludes deleted properties from all counts - Returns 0 for any status with no properties - No date range filtering (returns current counts only) For historical data or date-based analytics, you'll need to: 1. Poll this endpoint periodically and store results 2. Or use the search endpoint with date filters to calculate historical counts

Last updated on Dec 06, 2025

Property Aggregations

Get aggregated property statistics grouped by location and property type. Perfect for building mega menus, filter dropdowns, and third-party widgets that display property inventory. Endpoint Authentication Required. All API requests must be authenticated using your API key. See the Authentication section in the API Overview documentation. Query Parameters Parameter Type Description Default filterByOrganization boolean Filter results to only your organization's properties false status string Filter by listing status (active, pending, inactive, sold, rented) active Note: When filterByOrganization=false (default), the endpoint returns aggregations for all properties across all organizations, making it ideal for public-facing displays and mega menus. Response Success Response (200 OK) Response Fields Field Type Description byCity object Property counts grouped by city and property type byRegion object Property counts grouped by region and property type byPropertyType object Total counts for each property type across all locations byPropertyCategory object Total counts for each property category availableCities string[] Alphabetically sorted list of all cities with properties availableRegions string[] Alphabetically sorted list of all regions with properties availablePropertyTypes string[] Alphabetically sorted list of all property types available availablePropertyCategories string[] Alphabetically sorted list of all property categories available totalProperties number Total count of properties matching the filters Location Aggregation Object Each location (city or region) contains: - total: Total number of properties in that location - byType: Object with property type as key and count as value Error Responses 401 Unauthorized 400 Bad Request Example Requests Get All Active Properties Aggregations Get Organization's Properties Only Filter by Status Combined Filters Code Examples JavaScript/TypeScript Python PHP Use Cases 1. Dynamic Mega Menu Build a mega menu that displays available properties by location and type: 2. Filter Dropdown with Counts Create dynamic filter options showing available counts: 3. Location-Based Landing Pages Generate SEO-friendly landing pages for each location: 4. Third-Party Widget Embed property inventory widget on external websites: 5. Interactive Map Sidebar Build a sidebar that shows available properties in each region: 6. Search Suggestions with Counts Show search suggestions with property counts: 7. Property Type Comparison Chart Create a visual breakdown of property inventory: 8. Featured Locations Carousel Showcase top locations with inventory counts: Tips and Best Practices 1. Caching: Cache aggregations for 5-15 minutes to reduce API calls: 2. Combine with Search: Use aggregations to build filters, then use the search endpoint to fetch actual properties: 3. Public vs Private: - Use filterByOrganization=false (default) for public-facing mega menus showing all inventory - Use filterByOrganization=true for internal dashboards showing only your listings 4. Status Filtering: - Default status=active is ideal for public-facing displays - Use status=pending to build internal review interfaces - Multiple statuses not currently supported (use search endpoint for that) 5. Empty Locations: Locations without properties won't appear in the response, making the data clean and ready for rendering 6. Alphabetical Sorting: All available* arrays are pre-sorted alphabetically for consistent UI rendering 7. Performance: This endpoint is highly optimized with database indexes and typically responds in under 150ms, making it suitable for real-time mega menus 8. Link Generation: Use city/region names directly in URL parameters: 9. Mobile Optimization: For mobile mega menus, consider showing only top N cities: 10. SEO Benefits: Use aggregations to generate: - Dynamic sitemaps with property count estimates - Meta descriptions mentioning property counts - Structured data (Schema.org) with aggregate ratings Response Time This endpoint is optimized with database indexes and typically responds in under 150ms. It performs efficient GROUP BY queries on the property database and is safe to call for every page load. Limitations - Only one status filter at a time (use search endpoint for multiple statuses) - No date range filtering (shows current snapshot only) - Empty locations (no properties) won't appear in results - Property type and category names are stored as-is (no normalization) - Maximum of 1000 unique cities/regions per request (unlikely to hit this limit) Related Endpoints - Search Properties (POST /properties/search) - Fetch actual property listings after filtering - Property Stats (GET /properties/stats/counts) - Get status-based counts for your organization - Get Property (GET /properties/:id) - Fetch individual property details Common Integration Pattern

Last updated on Dec 06, 2025