# List properties Searches the properties your agency publishes on its website. Filter by location, operation, category, price in any currency, rooms, area, agent and amenities. Source: https://dev.alterestate.com/properties/list Last updated: 2026-10-13 Use the Properties API to show your AlterEstate inventory on a website, a portal or an app. Results only include listings marked to show on the website, and they come from the agency that owns the public token. | Capability | Endpoint | | --- | --- | | Search and filter listings | GET /api/v1/properties/filter/ | | Get a listing’s full detail | GET /api/v1/properties/view/{slug}/ | | Create a listing | POST /api/v1/properties/create/ | | Update a listing | PATCH /api/v1/properties/edit/{uid}/ | ```http GET https://secure.alterestate.com/api/v1/properties/filter/ ``` Authentication: `aetoken: your_public_token` | Parameter | In | Type | Required | Group | Description | | --- | --- | --- | --- | --- | --- | | `page` | query | integer | no | Pagination | Page number. Defaults to 1. | | `page_size` | query | integer | no | Pagination | Results per page. Default and maximum: 30. | | `city` | query | number | no | Location | City ID. Repeat the parameter to match several cities. Get IDs from Locations. | | `city_name` | query | string | no | Location | City name, case and accent insensitive. For example Santo Domingo, Santiago or Ciudad de México. | | `sector` | query | number | no | Location | Sector ID. Repeat the parameter to match several sectors. | | `search` | query | string | no | Location | Free text, case and accent insensitive. Matches sector or neighborhood names (Naco, Bella Vista, Reforma) and listing codes (cid, uid or internal code). | | `listing_type` | query | number | no | Operation and category | 1 sale, 2 rent (includes nightly rentals), 3 nightly rental, 4 furnished rental. Required for price filters. | | `category` | query | number | no | Operation and category | Category ID. Repeat to match several. See Categories below. | | `condition` | query | number | no | Operation and category | 9 ready to move in, 5 under construction. Repeat to match both. | | `is_furnished` | query | boolean | no | Operation and category | true returns only listings with a furnished sale or rent price. | | `currency` | query | string | no | Price | Currency of value_min and value_max: USD, DOP, MXN, COP, CRC, GTQ or PEN. | | `value_min` | query | number | no | Price | Minimum price. Needs currency and listing_type. | | `value_max` | query | number | no | Price | Maximum price. Needs currency and listing_type. | | `rooms` | query | number | no | Features | Exact number of bedrooms. | | `rooms_min` | query | number | no | Features | Minimum bedrooms. | | `rooms_max` | query | number | no | Features | Maximum bedrooms. | | `bathrooms` | query | number | no | Features | Exact number of bathrooms. | | `bath_min` | query | number | no | Features | Minimum bathrooms. | | `bath_max` | query | number | no | Features | Maximum bathrooms. | | `parkings` | query | number | no | Features | Exact number of parking spaces. | | `parking_min` | query | number | no | Features | Minimum parking spaces. | | `parking_max` | query | number | no | Features | Maximum parking spaces. | | `area_min` | query | number | no | Features | Minimum built area in m². | | `area_max` | query | number | no | Features | Maximum built area in m². | | `agents` | query | string | no | Agents and amenities | Agent uid. Separate several with commas. Get uids from Users. | | `features` | query | number | no | Agents and amenities | Amenity ID. Repeat to require several; a listing must have all of them. | | `updated_after` | query | date | no | Sync | Listings updated on or after this date (YYYY-MM-DD). Useful for incremental syncs. | | `updated_before` | query | date | no | Sync | Listings updated on or before this date (YYYY-MM-DD). | | `sort` | query | string | no | Sorting | Field to sort by. Prefix with - for descending. See Sorting below. Defaults to newest first. | Example request: ```bash curl --request GET \ --url 'https://secure.alterestate.com/api/v1/properties/filter/?city=156&listing_type=1&category=1¤cy=USD&value_min=150000&value_max=250000' \ --header 'aetoken: your_public_token' \ --header 'Accept: application/json' ``` Response 200 OK: ```json { "count": 74, "next": "https://secure.alterestate.com/api/v1/properties/filter/?page=2", "previous": null, "results": [ { "cid": 292960, "uid": "JSORJ9S5AY", "name": "Modern apartment in Naco", "slug": "modern-apartment-in-naco-292960", "category": { "id": 1, "name": "Apartamentos", "name_en": "Apartments" }, "listing_type": [ { "id": 1, "listing": "Venta" } ], "sale_price": 185000, "currency_sale": "USD", "city": "Distrito Nacional", "sector": "Naco", "room": 2, "bathroom": 2, "parkinglot": 1, "property_area": 110, "short_description": "Bright apartment, ready to move in." } ] } ``` Response 400 Bad Request: ```json { "listing_type": "listing_type debe ser 1 (venta), 2 (alquiler), 3 (alquiler x noche) o 4 (alquiler amueblado)." } ``` ## Price filtering across currencies AlterEstate stores every listing price in its own currency and also normalized to USD. When you send value_min, value_max, currency and listing_type, the conversion happens on the server with AlterEstate’s internal exchange rates. You never convert prices in your frontend. | Step | Value | | --- | --- | | Listing price | RD$4,000,000 | | Query currency | USD | | Exchange rate | 58.00 | | Normalized price | 4,000,000 / 58 = US$68,965 | | Matches | value_min=65000&value_max=70000¤cy=USD&listing_type=1 | ## Categories | ID | Category | | --- | --- | | 1 | Apartments | | 2 | Houses | | 3 | Buildings | | 4 | Lots | | 5 | Hotels | | 6 | Commercial spaces | | 7 | Industrial warehouses | | 10 | Penthouses | | 13 | Villas | | 14 | Lofts | | 17 | Townhouses | ## Common amenity IDs | ID | Amenity | | --- | --- | | 74 | Pool | | 73 | Gym | | 77 | Shared terrace | | 516 | Private terrace | | 66 | Appliances included (línea blanca) | ## Sorting | Value | Sorts by | | --- | --- | | us_saleprice / -us_saleprice | Sale price in USD, ascending / descending. | | us_rentprice / -us_rentprice | Long-term rent in USD. | | us_rentalprice / -us_rentalprice | Nightly rental in USD. | | us_furnished / -us_furnished | Furnished rent in USD. | | timestamp / -timestamp | Date the listing was created. | | room, bathroom, parkinglot | Bedrooms, bathrooms or parking spaces. | | name, cid, view_count | Name, listing code or number of views. | ## Status codes | Status | Meaning | | --- | --- | | 200 | The request succeeded. | | 400 | A parameter or the body is invalid. The response names the field. | | 401 | The token is missing or invalid. | | 404 | The resource or route does not exist. | | 429 | Too many requests. Wait and retry. | | 500 | Server error while processing the request. | > Error messages are returned in Spanish. If the agency shares inventory with collaborating agencies, their listings appear after the agency’s own. If the agency limits its website to certain provinces, only listings in those provinces are returned. - [Retrieve a property](https://dev.alterestate.com/properties/retrieve) - [City and sector IDs](https://dev.alterestate.com/locations) - [Agent uids](https://dev.alterestate.com/users) ## FAQ ### How does AlterEstate filter property prices across currencies? Send currency, listing_type, value_min and value_max. AlterEstate converts each listing with its internal exchange rate, so a RD$4,000,000 listing matches a USD range of 65,000 to 70,000 at a rate of 58. ### How many properties does each page return? Up to 30. Use page to move through results and page_size to request fewer. ### How do I sync only the listings that changed? Send updated_after with the date of your last sync (YYYY-MM-DD). Only listings updated on or after that date are returned. ### Where do I get city and sector IDs? Call GET /api/v1/cities/?country= and GET /api/v1/sectors/?city=. Neither needs a token.