The LeadHQL API gives you programmatic access to property listings, agents, and related resources. Use it to integrate LeadHQL data into your own applications, websites, and workflows.

Base URL

All API requests are made to:

https://api.leadhql.com

Authentication

Every request must include an API key in the Authorization header:

Authorization: Bearer leadhql_pk_xxxxxxxxxxxxxxxxxxxxxxxx

See the Authentication page for details on creating and managing API keys.

Response Format

All successful responses return JSON. A typical list response includes the data and a total count:

{
  "results": [ ... ],
  "total": 142
}

Single-resource responses return the object directly:

{
  "id": "a1b2c3d4-...",
  "referenceNumber": "HQL-12345",
  "listingType": "sale",
  "propertyType": "villa",
  ...
}

Error Format

Errors return an appropriate HTTP status code with a JSON body:

{
  "statusCode": 404,
  "message": "Property with ID a1b2c3d4-... not found",
  "error": "Not Found"
}

Common Status Codes

| Code | Meaning | |------|---------| | 200 | Success | | 201 | Resource created | | 400 | Bad request — invalid parameters or validation failure | | 401 | Unauthorized — missing or invalid API key | | 403 | Forbidden — insufficient permissions | | 404 | Resource not found | | 429 | Rate limit exceeded |

Validation Errors

When request body validation fails, the response includes details about which fields are invalid:

{
  "statusCode": 400,
  "message": [
    "Country code must be exactly 2 characters (ISO 3166-1 alpha-2)",
    "Currency must be 3 uppercase letters (e.g., EUR, USD, GBP)"
  ],
  "error": "Bad Request"
}

Pagination

List endpoints use page-based pagination with two parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | page | integer | 1 | Page number (1-indexed) | | limit | integer | 20 | Items per page (1–100) |

The response includes a total field so you can calculate the number of pages:

curl -X POST https://api.leadhql.com/properties/search \
  -H "Authorization: Bearer leadhql_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"page": 2, "limit": 10}'

{
  "results": [ ... ],
  "total": 142
}

Total pages = Math.ceil(total / limit).

Rate Limits

The API enforces rate limits per authentication token:

| Window | Max Requests | |--------|-------------| | 1 minute | 20 | | 10 minutes | 100 | | 1 hour | 500 |

When you exceed a limit, the API returns 429 Too Many Requests. Back off and retry after the window resets.

Dual Authentication

All property and agent endpoints accept both JWT tokens (from the LeadHQL dashboard) and API keys. This means the same endpoints power both the dashboard UI and external integrations.

API Overview