Create, Read, Update, Delete Properties

Create, retrieve, update, and delete individual property listings. Also includes endpoints for renewing listings and finding properties that are about to expire.

Create a Property

Authentication: Required (API key or JWT)

Creates a new property listing for your organization. A unique reference number in the format HQL-XXXXX is automatically assigned.

Request Body

Required fields:

| Field | Type | Description | Constraints | |-------|------|-------------|-------------| | listingType | string | Listing type | sale, rent, sale_or_rent, fraction | | propertyCategory | string | Property category | residential, commercial, industrial, land | | propertyType | string | Property type | See Search Properties for full list | | city | string | City name | Non-empty string | | countryCode | string | Country code | ISO 3166-1 alpha-2 (2 uppercase letters, e.g., ES) | | currency | string | Currency code | ISO 4217 (3 uppercase letters, e.g., EUR) |

Optional fields:

| Field | Type | Description | Constraints | |-------|------|-------------|-------------| | description | string | Property description | — | | translatedDescriptions | object | Descriptions in other languages | { "es": "...", "fr": "..." } | | addressLine1 | string | Street address | — | | addressLine2 | string | Additional address | — | | postalCode | string | Postal / ZIP code | — | | provinceState | string | Province or state | — | | region | string | Region name | — | | community | string | Community or neighborhood | — | | latitude | number | Latitude | -90 to 90 | | longitude | number | Longitude | -180 to 180 | | price | number | Listing price | >= 0 | | bedrooms | number | Number of bedrooms | >= 0 | | bathrooms | number | Number of bathrooms | >= 0 | | livingArea | number | Living area size | >= 0 | | plotArea | number | Plot area size | >= 0 | | areaUnit | string | Unit for area fields | e.g., sqm, sqft | | yearBuilt | number | Year of construction | 1800 to current year + 5 | | isNewConstruction | boolean | New build flag | — | | energyRatingDetails | string | Energy rating info | — | | hasPool | boolean | Swimming pool | — | | hasSeaView | boolean | Sea view | — | | hasGarage | boolean | Garage | — | | hasTerrace | boolean | Terrace | — | | hasGarden | boolean | Garden | — | | isFurnished | boolean | Furnished | — | | hasAirConditioning | boolean | Air conditioning | — | | hasLift | boolean | Elevator / lift | — | | images | array | Property images | [{ url, alt?, order, isFeatured? }] | | thumbnails | array | Thumbnail images | [{ url, alt?, order, originalImageIndex }] | | additionalFeatures | object | Custom key-value features | — | | commission | number | Agent commission % | 0–100 | | leadGroupId | number | Associated lead group | — | | agentId | string | Assigned agent ID | — | | autoRenewEnabled | boolean | Auto-renew listing | — |

Example

curl -X POST https://api.leadhql.com/properties \
  -H "Authorization: Bearer leadhql_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "listingType": "sale",
    "propertyCategory": "residential",
    "propertyType": "villa",
    "city": "Marbella",
    "countryCode": "ES",
    "currency": "EUR",
    "price": 1250000,
    "bedrooms": 4,
    "bathrooms": 3,
    "livingArea": 320,
    "plotArea": 800,
    "areaUnit": "sqm",
    "hasPool": true,
    "hasSeaView": true,
    "description": "Stunning sea-view villa in Nueva Andalucía with private pool and landscaped garden."
  }'

Response

Returns the full created property object with the generated id and referenceNumber.

Get a Property

Authentication: Required (API key or JWT)

Path Parameters

| Parameter | Type | Description | |-----------|------|-------------| | id | UUID | Property ID |

Query Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | filterByOrganization | boolean | false | Restrict to your organization's properties | | includeBranding | boolean | false | Include organization branding data | | includeAdCount | boolean | false | Include count of ad creatives | | includeAdCreatives | boolean | false | Include full ad creative data |

Example

curl https://api.leadhql.com/properties/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer leadhql_pk_abc123"

Errors

| Status | Condition | |--------|-----------| | 404 | Property not found |

Update a Property

Authentication: Required (API key or JWT)

Updates an existing property. Only include the fields you want to change — all fields are optional. The property must belong to your organization.

Request Body

All fields from the create endpoint are available, plus:

| Field | Type | Description | |-------|------|-------------| | status | string | Change listing status: active, inactive, pending, sold, rented, deleted |

Example

curl -X PUT https://api.leadhql.com/properties/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer leadhql_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 1150000,
    "status": "active",
    "description": "Price reduced! Stunning sea-view villa in Nueva Andalucía."
  }'

Errors

| Status | Condition | |--------|-----------| | 404 | Property not found or not owned by your organization |

Delete a Property

Authentication: Required (API key or JWT)

Permanently deletes a property listing. The property must belong to your organization.

Example

curl -X DELETE https://api.leadhql.com/properties/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer leadhql_pk_abc123"

Response

{
  "success": true
}

Errors

| Status | Condition | |--------|-----------| | 404 | Property not found or not owned by your organization |

Renew a Property

Authentication: Required (API key or JWT)

Extends the expiration date of a property listing by 2 months. The property must belong to your organization.

Example

curl -X PUT https://api.leadhql.com/properties/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/renew \
  -H "Authorization: Bearer leadhql_pk_abc123"

Response

Returns the full updated property object with the new expiresAt date.

Errors

| Status | Condition | |--------|-----------| | 404 | Property not found or not owned by your organization |

Get Expiring Properties

Authentication: Required (API key or JWT)

Returns properties in your organization that are expiring within a given number of days.

Query Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | days | number | 7 | Number of days to look ahead |

Example

curl "https://api.leadhql.com/properties/expiring/soon?days=14" \
  -H "Authorization: Bearer leadhql_pk_abc123"

Response

Returns an array of property objects that will expire within the specified timeframe.