Website API

Build a property website on your live PropertyList listings, agency branding and new developments. A read-only JSON API.

On this page
Authentication Rate limits Properties Single property Agency & branding New developments Autocomplete

Base URL: https://api.propertylist.es All responses are JSON.

Get a key from Settings → Import & Exports in your CRM. Any manager can create a Website API key instantly.

Website API access is 35 credits/month per agency (flat - create as many keys as you need), billed to your CRM wallet. The first key starts the subscription.

Authentication

Send your Website API key as a bearer token on every request:

curl https://api.propertylist.es/v2/properties \
  -H "Authorization: Bearer YOUR_WEBSITE_API_KEY"

Website API keys are read-only and scoped to public-safe data - your listings, agency branding and new developments. They never expose private CRM data (contacts, leads, calendar), so they're safe to use in a public website.

Rate limits

Each Website API key may make 600 requests per minute. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) headers so you can pace yourself. Going over the limit returns 429 Too Many Requests with a Retry-After header; it never invalidates your key. A full catalogue read at page_size=100 needs a few dozen requests, well inside the limit.

A 401 Unauthorized is never a rate limit. Its JSON body carries a reason: key_suspended (the monthly renewal could not be charged; top up credits and the same key resumes working), key_revoked (rotated or revoked in the CRM; use the current key) or invalid_key.

Properties website key ok

GET/v2/properties

Paginated list of properties. By default you get your agency's own (direct) listings only. To include listings shared with you by other agencies, add shared=true (see note below).

Parameter	Description
`direct`	`true` (default) includes your agency's own listings. Set `direct=false` to exclude them.
`shared`	`false` (default). Set `shared=true` to also return listings shared with you by other agencies. Combine `direct=false&shared=true` to return shared listings only.
`search_type`	`for-sale`, `long-term` or `short-term`
`page`, `page_size`	Page number (from 1); page size 1-100 (default 20; larger values are capped). `per_page` is accepted as an alias. The response includes `total_count` and `total_pages`.
`property_types`	Comma list: `apartment,villa,penthouse,townhouse,plot,country-house`
`locations`	Comma list of area IDs (see autocomplete)
`provinces`	Comma list of province codes, e.g. `MA,CA`
`bedrooms_min`, `bathrooms_min`	Minimums
`price_min`, `price_max`	Price band
`build_min`, `plot_min`	Minimum m²
`features`, `orientations`	Comma lists of slugs
`reference`, `ids`	Find by your reference, or specific IDs
`sort`	`date_new_old`, `date_old_new`, `price_low_high`, `price_high_low`
`language`	Description language, e.g. `en`, `es`

Seeing only your own properties? That is the default. To pull in the wider shared inventory, pass shared=true. This also requires your agency to have sharing switched on ("Share my listings") in your CRM under Settings; if it is off, shared=true returns your own listings only. Each property in the response carries a direct flag (true = your own listing, false = shared by another agency).

{
  "page": 1,
  "page_size": 20,
  "total_count": 142,
  "total_pages": 8,
  "data": [
    {
      "id": 12345,
      "reference": "AB-1001",
      "is_sale": true,
      "for_sale_price": 495000,
      "currency": "EUR",
      "bedrooms": 3, "bathrooms": 2,
      "build": 120, "plot": 400, "terrace": 30,
      "province": "MA", "city": "Marbella", "suburb": "Nueva Andalucia",
      "latitude": 36.51, "longitude": -4.95, "coordinates_precision": "exact",
      "property_type": "Villa",
      "energy_rating": "C",
      "photo": "https://.../small.jpg",
      "photo_large": "https://.../medium.jpg",
      "description": "...",
      "features": ["private-pool","sea-views"]
    }
  ]
}

Coordinates. latitude and longitude are present on both the list and the single-property response, but only when we hold a real, publishable point for that listing. They are omitted entirely when the listing has no coordinate or the agent has marked its map position private, and they are never 0,0. Treat a missing pair as "unknown", not as a point at zero. coordinates_precision tells you what the point is: exact or street is the property itself, locality or administrative_area is an area centroid (right town, not the building) that came from geocoding a feed address, and unknown is a pin we hold no precision record for. Filter on it before you draw a pin at street level.

Single property website key ok

GET/v2/properties/:id

Full detail for one property: all descriptions, every photo size, rental terms, taxes (IBI, community fees), energy rating and similar properties. Carries the same latitude, longitude and coordinates_precision fields as the list, under the same rules.

Agency & branding website key ok

GET/v2/agency

Everything you need to render the site shell: name, logo, contact, address.

{
  "id": 42,
  "name": "Costa Real Estate",
  "website": "https://...",
  "contact": { "email": "info@...", "phone": "+34 ...", "contact_person": "..." },
  "address": { "line_1": "...", "postcode": "29660", "city": "Marbella" },
  "logo": { "default": "https://...", "large": "https://..." },
  "office_photo": "https://..."
}

New developments website key ok

GET/v2/developments

GET/v2/developments/:id

Off-plan / new-build projects: title, price range, units available, completion date, location and coordinates.

Autocomplete website key ok

GET/v2/autocomplete/location-or-property?q=marbella

Resolve a search term to area IDs (use the returned id in locations) or matching properties.

Questions? [email protected]