Listings

The Listing object represents a property listing in the EstatePrime system. This object is returned in JSON format, containing all available values for a listing including its details, location, photos, translations, and related contacts.

Object

The Listing object represents an individual property listing. Below are the fields included in a Listing object:

Example

{
  "id": 120,
  "store_id": 2,
  "code": "RES-00120",
  "category": "residential",
  "subcategory": "apartment",
  "availability": "sale",
  "price": 180000,
  "price_per_sqm": 2000.00,
  "size": 90.00,
  "floor": 2,
  "levels": 1,
  "rooms": 3,
  "bathrooms": 1,
  "year_built": 2005,
  "property_condition": "good",
  "status": "active",
  "status_date": "2025-01-10 09:00:00",
  "source_id": 1,
  "created_by": 3,
  "date_created": "2025-01-10 09:00:00",
  "date_updated": "2025-03-05 14:30:00",
  "wcs": 1,
  "living_rooms": 1,
  "kitchens": 1,
  "master_bedrooms": 1,
  "assignment": "exclusive",
  "assignment_fee": 2.50,
  "assignment_fee_type": "percent",
  "assignment_expires": "2025-12-31",
  "total_building_floors": 6,
  "heating_type": "autonomous",
  "heating_source": "natural_gas",
  "frames": "aluminum",
  "frames_glass": "double",
  "parking_open_sheltered": 0,
  "parking_open_unsheltered": 0,
  "parking_garage": 1,
  "parking_total": 1,
  "construction_type": "concrete",
  "year_renovated": null,
  "land_size": null,
  "garden": null,
  "zoning": null,
  "coverage_ratio": null,
  "build_ratio": null,
  "max_height": null,
  "youtube_url": null,
  "virtual_tour_url": null,
  "distance_sea": null,
  "distance_airport": null,
  "distance_city": null,
  "distance_market": null,
  "monthly_maintenance": 80,
  "tenant_contact_id": null,
  "available_from": null,
  "has_keys": true,
  "is_rented": false,
  "has_hidden_price": false,
  "orientation": "se",
  "energy_class": "b",
  "is_negotiable": true,
  "frontage_length": null,
  "land_slope": null,
  "access_type": null,
  "floor_configuration": null,
  "shortterm_unit": null,
  "shortterm_min_stay": null,
  "shortterm_max_guests": null,
  "auction_code": null,
  "auction_date": null,
  "auction_url": null,
  "notes": "Owner prefers serious buyers only.",
  "location": {
    "area_level1": {
      "id": 5,
      "name_el": "Θεσσαλονίκη",
      "name_en": "Thessaloniki",
      "full_name_el": "Θεσσαλονίκη",
      "full_name_en": "Thessaloniki"
    },
    "area_level2": {
      "id": 12,
      "name_el": "Δήμος Θεσσαλονίκης",
      "name_en": "Municipality of Thessaloniki",
      "full_name_el": "Θεσσαλονίκη > Δήμος Θεσσαλονίκης",
      "full_name_en": "Thessaloniki > Municipality of Thessaloniki"
    },
    "area_level3": null,
    "postal_code": "54623",
    "display_address": true,
    "show_circle_on_map": false,
    "address_el": "Τσιμισκή 15",
    "fake_address_el": null,
    "longitude": 22.9444,
    "latitude": 40.6401,
    "fake_longitude": null,
    "fake_latitude": null
  },
  "features": ["elevator", "storage", "alarm"],
  "positioning": ["corner", "seafront"],
  "view": ["sea_view", "mountain_view"],
  "flooring": ["marble", "tile"],
  "tags": [2, 7],
  "contacts": [23, 45],
  "users": [3, 8],
  "photos": [
    {
      "original_image": "https://files.example.com/listings/120/photo1.jpg",
      "watermark_image": "https://files.example.com/listings/120/photo1_wm.jpg"
    },
    {
      "original_image": "https://files.example.com/listings/120/photo2.jpg",
      "watermark_image": null
    }
  ],
  "translations": [
    {
      "language_id": 1,
      "title": "Apartment in Thessaloniki",
      "description": "Spacious 3-bedroom apartment in the city center."
    },
    {
      "language_id": 2,
      "title": "Διαμέρισμα στη Θεσσαλονίκη",
      "description": "Ευρύχωρο τριάρι στο κέντρο της πόλης."
    }
  ]
}

Core fields

• id (int): The system id of the listing.
• store_id (int): The ID of the office/store that owns the listing.
• code (string, nullable): The human-readable listing code (e.g., RES-00120).
• category (string): The property category. Possible values: residential, commercial, land, other.
• subcategory (string): The property subcategory. Possible values: apartment, maisonette, detached, villa, loft, residential_building, apartment_complex, farmhouse, houseboat, other_residential, office, store, warehouse, hotel, commercial_building, hall, industrial_space, craft_space, other_commercial, plot, parcel, island, parking, business, air, other.
• availability (string): The listing availability type. Possible values: sale, rent, auction, shortterm.
• price (int, nullable): The listing price.
• price_per_sqm (decimal, nullable): The price per square meter.
• size (decimal, nullable): The property size in square meters.
• floor (float, nullable): The floor number of the property.
• levels (int, nullable): The number of levels/floors the property spans.
• rooms (int, nullable): The number of rooms/bedrooms.
• bathrooms (int, nullable): The number of bathrooms.
• year_built (int, nullable): The year the property was built.
• property_condition (string, nullable): The condition of the property. Possible values: under_construction, new, renovated, good, average, needs_renovation, unfinished.
• status (string): The listing status. Possible values: draft, pending, active, inactive, archived, deleted.
• status_date (string, nullable): The date and time the status was last changed in YYYY-MM-DD HH:MM:SS format.
• source_id (int, nullable): The ID of the source from which the listing originated.
• created_by (int): The user ID of the user who created the listing.
• date_created (string): The date and time the listing was created in YYYY-MM-DD HH:MM:SS format.
• date_updated (string): The date and time the listing was last updated in YYYY-MM-DD HH:MM:SS format.

Detail fields (from listings_details)

• wcs (int, nullable): Number of WCs.
• living_rooms (int, nullable): Number of living rooms.
• kitchens (int, nullable): Number of kitchens.
• master_bedrooms (int, nullable): Number of master bedrooms.
• assignment (string, nullable): Assignment type. Possible values: none, simple, exclusive.
• assignment_fee (decimal, nullable): Assignment fee amount.
• assignment_fee_type (string, nullable): Whether the fee is a fixed amount or percentage. Possible values: fixed, percent.
• assignment_expires (string, nullable): Assignment expiry date in YYYY-MM-DD format.
• total_building_floors (int, nullable): Total number of floors in the building.
• heating_type (string, nullable): Heating system type. Possible values: individual, autonomous, central, none.
• heating_source (string, nullable): Heating energy source. Possible values: oil, natural_gas, gas, ac, heatpump, wood, pellet, fan_coil, geothermal_energy, stove, convection_heater, storage_heater, teleheating, other.
• frames (string, nullable): Window frame material. Possible values: aluminum, wood, synthetic, pvc.
• frames_glass (string, nullable): Window glazing type. Possible values: single, double, triple.
• parking_open_sheltered (int, nullable): Number of open sheltered parking spaces.
• parking_open_unsheltered (int, nullable): Number of open unsheltered parking spaces.
• parking_garage (int, nullable): Number of garage parking spaces.
• parking_total (int, nullable): Total parking spaces.
• construction_type (string, nullable): Construction material. Possible values: concrete, wood, metal, prefab, portable, stone.
• year_renovated (int, nullable): Year of last renovation.
• land_size (decimal, nullable): Land/plot size in square meters.
• garden (string, nullable): Garden type. Possible values: shared, private, roof_garden.
• zoning (string, nullable): Zoning classification. Possible values: residential, unzoned, commercial, industrial, light_industrial, agricultural, tourist, archaeological, forest, protected.
• coverage_ratio (decimal, nullable): Coverage ratio percentage.
• build_ratio (decimal, nullable): Build ratio (floor area ratio).
• max_height (decimal, nullable): Maximum permitted building height in meters.

Extra fields (from listings_extras)

• youtube_url (string, nullable): A YouTube video URL for the listing.
• virtual_tour_url (string, nullable): A virtual tour URL.
• distance_sea (int, nullable): Distance to the sea in meters.
• distance_airport (int, nullable): Distance to the airport in meters.
• distance_city (int, nullable): Distance to the city center in meters.
• distance_market (int, nullable): Distance to a market/supermarket in meters.
• monthly_maintenance (int, nullable): Monthly maintenance fee.
• tenant_contact_id (int, nullable): Contact ID of the current tenant (for rented properties).
• available_from (string, nullable): Date the property becomes available in YYYY-MM-DD format.
• has_keys (boolean): Whether the agency holds the property keys.
• is_rented (boolean): Whether the property is currently rented.
• has_hidden_price (boolean): Whether the price is hidden on portals.
• orientation (string, nullable): Property orientation. Possible values: e, ew, n, ne, w, nw, s, se, sw.
• energy_class (string, nullable): Energy efficiency class. Possible values: ap, a, bp, b, c, d, e, f, g.
• is_negotiable (boolean): Whether the price is negotiable.
• frontage_length (decimal, nullable): Street frontage length in meters.
• land_slope (string, nullable): Land slope type. Possible values: flat, sloped, amphitheatrical.
• access_type (string, nullable): Property access type. Possible values: road, dirt_road, sea, pedestrian, no_access.
• floor_configuration (object, nullable): JSON object describing multi-floor configuration details.
• shortterm_unit (string, nullable): Short-term rental pricing unit. Possible values: per_day, per_week, per_month, per_season, per_year.
• shortterm_min_stay (int, nullable): Minimum stay duration for short-term rentals.
• shortterm_max_guests (int, nullable): Maximum number of guests for short-term rentals.
• auction_code (string, nullable): Auction reference code.
• auction_date (string, nullable): Auction date in YYYY-MM-DD format.
• auction_url (string, nullable): URL to the auction listing.

Relation fields

• notes (string, nullable): Internal notes about the listing.
• location (object): Location data. Contains the following fields:
  • area_level1 (object, nullable): Region data: id, name_el, name_en, full_name_el, full_name_en.
  • area_level2 (object, nullable): Municipality/district data: same fields as area_level1.
  • area_level3 (object, nullable): Neighbourhood data: same fields as area_level1.
  • postal_code (string, nullable): The postal code.
  • display_address (boolean): Whether to display the full address publicly.
  • show_circle_on_map (boolean): Whether to show a privacy circle instead of an exact pin on the map.
  • address_el (string, nullable): The street address in Greek.
  • fake_address_el (string, nullable): A fake/privacy address used publicly when exact address is hidden.
  • longitude (float, nullable): Exact GPS longitude coordinate.
  • latitude (float, nullable): Exact GPS latitude coordinate.
  • fake_longitude (float, nullable): Privacy longitude used on public maps.
  • fake_latitude (float, nullable): Privacy latitude used on public maps.
• features (array of strings): A list of general feature keys (e.g., elevator, storage, alarm).
• positioning (array of strings): A list of positioning characteristic keys (e.g., corner, seafront).
• view (array of strings): A list of view characteristic keys (e.g., sea_view, mountain_view).
• flooring (array of strings): A list of flooring material keys (e.g., marble, tile).
• tags (array of integers): A list of tag IDs associated with the listing.
• contacts (array of integers): A list of contact IDs (owners) associated with the listing.
• users (array of integers): A list of user IDs (agents) responsible for the listing.
• photos (array of objects): A list of listing photos. Each object includes:
  • original_image (string, nullable): URL of the original photo.
  • watermark_image (string, nullable): URL of the watermarked version, or null if not generated.
• translations (array of objects): Listing title and description in each configured language. Each object includes:
  • language_id (int): The language ID.
  • title (string, nullable): The listing title in this language.
  • description (string, nullable): The listing description in this language.

Get listings

/api/listings (GET)

Fetch a paginated list of listings.

Request

• Method: GET
• Headers: Include authentication headers as described in the Authentication section.
• Body: JSON object with the following optional parameters:
  • page (int): The page number to fetch. Defaults to 1.
  • search (string): Search by listing code or ID (exact match).
  • availability (string or array): Filter by availability type. Accepted values: sale, rent, auction, shortterm. Pass a single string or an array for multiple values.
  • category (string or array): Filter by property category. Accepted values: residential, commercial, land, other. Pass a single string or an array for multiple values.
  • subcategory (string or array): Filter by property subcategory (e.g. apartment, office, plot). Pass a single string or an array for multiple values.
  • status (string or array): Filter by listing status. Accepted values: draft, pending, active, inactive, archived, deleted. Pass a single string or an array for multiple values.
  • date_created (object): Filter by creation date range. Must include:
    • min (string): The minimum date in YYYY-MM-DD HH:MM:SS format, or null for no lower limit.
    • max (string): The maximum date in YYYY-MM-DD HH:MM:SS format, or null for no upper limit.

Example Body

{
  "page": 1,
  "availability": ["sale", "auction"],
  "category": "residential",
  "status": "active",
  "date_created": {
    "min": "2025-01-01 00:00:00",
    "max": null
  }
}

Response

• 200 OK: Returns a JSON array of listing objects.

Example Response

{
  "status": 200,
  "page": 1,
  "total_pages": 14,
  "results_per_page": 50,
  "total_results": 692,
  "data": [
    {
      "id": 120,
      "store_id": 2,
      "code": "RES-00120",
      "category": "residential",
      "subcategory": "apartment",
      "availability": "sale",
      "price": 180000,
      "size": 90.00,
      "status": "active",
      "date_created": "2025-01-10 09:00:00",
      "date_updated": "2025-03-05 14:30:00",
      "location": { },
      "photos": [ ],
      "contacts": [23, 45],
      "users": [3, 8],
      "tags": [2, 7],
      "translations": [ ]
      //Rest of the fields...
    }
    //Rest of the data...
  ]
}

Get single listing

/api/listings/{id} (GET)

Get a single listing by its id.

Request

• Method: GET
• Headers: Include authentication headers.
• Path Params: The listing id to be fetched.

Example Response

{
  "status": 200,
  "data": {
    "id": 120,
    "store_id": 2,
    "code": "RES-00120",
    "category": "residential",
    "subcategory": "apartment",
    "availability": "sale",
    "price": 180000,
    "price_per_sqm": 2000.00,
    "size": 90.00,
    "floor": 2,
    "rooms": 3,
    "bathrooms": 1,
    "year_built": 2005,
    "property_condition": "good",
    "status": "active",
    "date_created": "2025-01-10 09:00:00",
    "date_updated": "2025-03-05 14:30:00",
    "location": {
      "area_level1": {
        "id": 5,
        "name_el": "Θεσσαλονίκη",
        "name_en": "Thessaloniki",
        "full_name_el": "Θεσσαλονίκη",
        "full_name_en": "Thessaloniki"
      },
      "area_level2": { },
      "area_level3": null,
      "postal_code": "54623",
      "address_el": "Τσιμισκή 15",
      "longitude": 22.9444,
      "latitude": 40.6401
    },
    "features": ["elevator", "storage"],
    "tags": [2, 7],
    "contacts": [23, 45],
    "users": [3, 8],
    "photos": [
      {
        "original_image": "https://files.example.com/listings/120/photo1.jpg",
        "watermark_image": "https://files.example.com/listings/120/photo1_wm.jpg"
      }
    ],
    "translations": [
      {
        "language_id": 1,
        "title": "Apartment in Thessaloniki",
        "description": "Spacious 3-bedroom apartment in the city center."
      }
    ]
    //Rest of the fields...
  }
}

Response

• 200 OK: Returns the JSON object of the listing.

Get listing sources

/api/listings/sources (GET)

Fetch the available listing sources.

Request

• Method: GET
• Headers: Include authentication headers.

Response

• 200 OK: Returns a JSON array of available listing sources.

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "Owner Direct"
    },
    {
      "id": 2,
      "name": "Agency Referral"
    }
  ]
}

Get listing tags

/api/listings/tags (GET)

Fetch the available listing tags.

Request

• Method: GET
• Headers: Include authentication headers.

Response

• 200 OK: Returns a JSON array of available listing tags.

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "Urgent Sale"
    },
    {
      "id": 2,
      "name": "Price Reduced"
    }
  ]
}

Get listing custom fields

/api/listings/custom-fields (GET)

Fetch the available custom fields for listings.

Request

• Method: GET
• Headers: Include authentication headers.

Response

• 200 OK: Returns a JSON array of available custom fields for listings.

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "Pool",
      "type": "checkbox"
    },
    {
      "id": 2,
      "name": "Condition Notes",
      "type": "textarea"
    },
    {
      "id": 3,
      "name": "View Type",
      "type": "select_multi",
      "options": [
        {
          "id": 1,
          "name": "Sea View"
        },
        {
          "id": 2,
          "name": "Mountain View"
        }
      ]
    }
  ]
}

Available custom field types

• text: Text up to 255 characters.
• textarea: Text up to 2500 characters.
• wysiwyg: Text with HTML format.
• number: Integer or decimal.
• formatted_number: Integer or decimal that is formatted. E.g. 1,000,000.25.
• select: Single select with options.
• select_multi: Multiple select with options.
• checkbox: Boolean.
• file: Single file. (As a URL)
• file_multi: Array of multiple files. (As URLs)
• image: Single image. (As a URL)
• image_multi: Array of multiple images. (As URLs)
• address: Address. (E.g. Bellariastraße 6, 1010 Wien, Austria)
• url: URL.
• date: Date in YYYY-MM-DD format. (E.g. 2025-10-18)
• datetime: Datetime in YYYY-MM-DD HH:MM:SS format. (E.g. 2025-10-18 18:24:10)
• currency: Integer or decimal formatted as a currency. E.g. 1,000,000.25€.
• user: Application user_id.
• user_multi: An array of application user_id values.
• contact: Another contact's id.
• contact_multi: An array of multiple contact ids.