Requests

The Request object represents a buyer's property search request in the EstatePrime system. This object is returned in JSON format, containing all available values for a request including its search criteria, locations, and related contacts.

Object

The Request object represents an individual buyer request. Below are the fields included in a Request object:

Example

{
  "id": 88,
  "date_created": "2025-02-05 11:20:00",
  "date_updated": "2025-03-10 09:15:00",
  "created_by": 3,
  "store_id": 2,
  "source_id": 1,
  "status": 1,
  "availability": "sale",
  "category": "residential",
  "subcategories": ["apartment", "maisonette"],
  "price_min": 100000,
  "price_max": 220000,
  "price_per_sqm_min": null,
  "price_per_sqm_max": null,
  "size_min": 70,
  "size_max": 120,
  "year_built_min": 2000,
  "year_built_max": null,
  "rooms_min": 2,
  "rooms_max": 3,
  "floor_min": null,
  "floor_max": null,
  "has_elevator": false,
  "extra_fields": {
    "1": "some value",
    "3": [2, 5]
  },
  "contacts": [23, 45],
  "users": [3, 8],
  "tags": [7, 12],
  "locations": [
    {
      "area_level1": 5,
      "area_level2": 12,
      "area_level3": null
    },
    {
      "area_level1": 5,
      "area_level2": 14,
      "area_level3": null
    }
  ]
}

• id (int): The system id of the request.
• date_created (string): The date and time the request was created in YYYY-MM-DD HH:MM:SS format.
• date_updated (string): The date and time the request was last updated in YYYY-MM-DD HH:MM:SS format.
• created_by (int): The user ID of the user who created the request.
• store_id (int): The ID of the office/store this request belongs to.
• source_id (int, nullable): The ID of the source from which the request originated.
• status (int): The request status ID. Fetch available statuses from /api/requests/statuses.
• availability (string): The desired availability type. Possible values: sale, rent, auction, shortterm.
• category (string): The desired property category. Possible values: residential, commercial, land, other.
• subcategories (array of strings): A list of desired property subcategory keys. 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.
• price_min (int, nullable): Minimum desired price.
• price_max (int, nullable): Maximum desired price.
• price_per_sqm_min (int, nullable): Minimum desired price per square meter.
• price_per_sqm_max (int, nullable): Maximum desired price per square meter.
• size_min (int, nullable): Minimum desired size in square meters.
• size_max (int, nullable): Maximum desired size in square meters.
• year_built_min (int, nullable): Minimum desired year of construction.
• year_built_max (int, nullable): Maximum desired year of construction.
• rooms_min (int, nullable): Minimum desired number of rooms/bedrooms.
• rooms_max (int, nullable): Maximum desired number of rooms/bedrooms.
• floor_min (float, nullable): Minimum desired floor number.
• floor_max (float, nullable): Maximum desired floor number.
• has_elevator (boolean): Whether the buyer requires an elevator.
• extra_fields (object): Custom field values keyed by custom field ID. Values vary by field type. Empty object {} if none are set.
• contacts (array of integers): A list of contact IDs associated with this request (the buyers).
• users (array of integers): A list of user IDs (agents) responsible for this request.
• tags (array of integers): A list of tag IDs associated with the request.
• locations (array of objects): A list of desired location areas. Each object includes:
  • area_level1 (int): Region ID. Always present.
  • area_level2 (int, nullable): Municipality/district ID, or null if the entire region is desired.
  • area_level3 (int, nullable): Neighbourhood ID, or null if the entire municipality is desired.

Get requests

/api/requests (GET)

Fetch a paginated list of requests.

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.
  • status (int): Filter by status ID. Fetch available statuses from /api/requests/statuses.
  • availability (string): Filter by availability type. Possible values: sale, rent, auction, shortterm.
  • category (string): Filter by property category. Possible values: residential, commercial, land, other.
  • store_id (int): Filter by office/store ID.
  • contact_id (int): Filter by associated contact ID.
  • user_id (int): Filter by associated agent user ID.
  • 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.
  • date_updated (object): Filter by last update 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,
  "status": 1,
  "availability": "sale",
  "category": "residential",
  "date_created": {
    "min": "2025-01-01 00:00:00",
    "max": null
  }
}

Response

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

Example Response

{
  "status": 200,
  "page": 1,
  "total_pages": 4,
  "results_per_page": 50,
  "total_results": 183,
  "data": [
    {
      "id": 88,
      "date_created": "2025-02-05 11:20:00",
      "date_updated": "2025-03-10 09:15:00",
      "created_by": 3,
      "store_id": 2,
      "source_id": 1,
      "status": 1,
      "availability": "sale",
      "category": "residential",
      "subcategories": ["apartment", "maisonette"],
      "price_min": 100000,
      "price_max": 220000,
      "size_min": 70,
      "size_max": 120,
      "rooms_min": 2,
      "rooms_max": 3,
      "has_elevator": false,
      "extra_fields": {},
      "contacts": [23, 45],
      "users": [3, 8],
      "tags": [7, 12],
      "locations": [
        {
          "area_level1": 5,
          "area_level2": 12,
          "area_level3": null
        }
      ]
    }
    //Rest of the data...
  ]
}

Get single request

/api/requests/{id} (GET)

Get a single request by its id.

Request

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

Example Response

{
  "status": 200,
  "data": {
    "id": 88,
    "date_created": "2025-02-05 11:20:00",
    "date_updated": "2025-03-10 09:15:00",
    "created_by": 3,
    "store_id": 2,
    "source_id": 1,
    "status": 1,
    "availability": "sale",
    "category": "residential",
    "subcategories": ["apartment", "maisonette"],
    "price_min": 100000,
    "price_max": 220000,
    "price_per_sqm_min": null,
    "price_per_sqm_max": null,
    "size_min": 70,
    "size_max": 120,
    "year_built_min": 2000,
    "year_built_max": null,
    "rooms_min": 2,
    "rooms_max": 3,
    "floor_min": null,
    "floor_max": null,
    "has_elevator": false,
    "extra_fields": {
      "1": "some value",
      "3": [2, 5]
    },
    "contacts": [23, 45],
    "users": [3, 8],
    "tags": [7, 12],
    "locations": [
      {
        "area_level1": 5,
        "area_level2": 12,
        "area_level3": null
      },
      {
        "area_level1": 5,
        "area_level2": 14,
        "area_level3": null
      }
    ]
  }
}

Response

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

Create request

/api/requests (POST)

Create a new request (a buyer's property search).

Request

• Method: POST
• Headers: Include authentication headers.
• Body: JSON object with the request details to be inserted. See Body parameters below.

Required fields

• availability (string): One of sale, rent, auction, shortterm.
• category (string): One of residential, commercial, land, other.
• contacts (array of integers): At least one existing contact ID (the buyer(s)). Contacts must not be soft-deleted.
• locations (array of integers): At least one existing location ID (any level — region, municipality, or neighbourhood).
• users (array of integers): At least one existing user ID to assign the request to.
• created_by (int): An existing user ID to record as the creator of the request.
• store_id (int): An existing office/store ID.

Optional fields

• title (string): Custom title. If omitted, a title is generated automatically from the category, availability, and up to 3 of the given locations.
• subcategories (array of strings): Property subcategory keys matching category (see the list in the Object section above). If omitted, all subcategories of the chosen category are used.
• subtypes (array of integers): IDs from listings_subtypes. Must belong to one of the resolved subcategories.
• price_min / price_max (int)
• price_per_sqm_min / price_per_sqm_max (int)
• size_min / size_max (int)
• year_built_min / year_built_max (int) — ignored/cleared when category is land.
• rooms_min / rooms_max (int) — ignored/cleared when category is land.
• floor_min / floor_max (number): Only applies when category is residential, commercial, or other. Allowed values: -1, -0.5, 0, 0.5, 1, 1.5, and whole numbers 2 to 127.
• has_elevator (boolean): Only applies when category is not land.
• elevator_min_floor (number): Only used when has_elevator is true.
• rating (int): 1 to 5.
• source_id (int): An ID from /api/requests/sources.
• status (int): An ID from /api/requests/statuses. Defaults to the account's default status.
• tags (array of integers): IDs from /api/requests/tags.
• notes (string): Free-text notes stored with the request.
• extra_fields (object): Additional search criteria, all optional. See extra_fields below.

Any min/max pair where min is greater than max is rejected.

extra_fields

All keys are optional; unlisted/unknown keys are ignored.

• view (array of strings): Any of sea, mountain, park, openspace, acropolis, city, lake, river, forest, panoramic.
• positioning (array of strings): Any of is_corner, is_front_facing, is_side_facing, is_through, is_interior, is_three_sided, is_four_sided.
• property_condition (array of strings): Any of under_construction, new, renovated, good, average, needs_renovation, unfinished.
• orientation (array of strings): Any of e, ew, n, ne, w, nw, s, se, sw.
• heating_type (array of strings): Any of individual, autonomous, central, none. Not applicable when category is land.
• heating_source (array of strings): Any of oil, natural_gas, gas, ac, heatpump, wood, pellet, fan_coil, geothermal_energy, stove, convection_heater, storage_heater, teleheating, other. Not applicable when category is land.
• construction_type (array of strings): Any of concrete, wood, metal, prefab, portable, stone. Not applicable when category is land.
• garden (array of strings): Any of shared, private, roof_garden. Not applicable when category is land.
• features (array of strings): Requested amenities, validated against the same list used for listings (e.g. has_elevator, has_parking, has_storage_room, has_balcony, has_fireplace, has_air_condition, has_security_door, is_furnished, has_underfloor_heating, has_private_pool, has_shared_pool, is_penthouse, is_luxurious, is_seaside, is_bright, pets_allowed, suitable_for_students, suitable_for_families, golden_visa, has_solar_heater, is_investment, has_disabled_access, and more). Each feature must be applicable to the chosen category, or it is rejected.
• is_furnished (string): yes or no. Not applicable when category is land.
• garden_size_min / garden_size_max (number)
• land_size_min / land_size_max (int) — only applicable when category is not land.
• parking_total_min / parking_total_max (int) — only applicable when category is not land.
• bathrooms_total_min / bathrooms_total_max (int) — only applicable when category is not land.
• build_ratio_min / build_ratio_max (number) — only applicable when category is land.
• coverage_ratio_min / coverage_ratio_max (number) — only applicable when category is land.
• yield_min (number, 0-99.99) — only applicable when availability is sale.
• shortterm_unit (string): One of per_day, per_week, per_month, per_season, per_year. Required when availability is shortterm.
• shortterm_max_guests_min / shortterm_max_guests_max (int) — only applicable when availability is shortterm.
• special_locations (array of integers): IDs of special points of interest (e.g. near a school/metro station).
• listing_tags (array of integers): Listing tag IDs that matched properties must carry.

Example Body

{
  "availability": "rent",
  "category": "residential",
  "contacts": [45],
  "locations": [12],
  "users": [3, 8],
  "created_by": 3,
  "store_id": 2,
  "subcategories": ["apartment"],
  "price_max": 500,
  "size_min": 50,
  "size_max": 70,
  "has_elevator": true,
  "source_id": 1,
  "tags": [7],
  "notes": "Looking for something close to the metro.",
  "extra_fields": {
    "view": ["sea"],
    "features": ["has_balcony", "has_storage_room"],
    "is_furnished": "yes"
  }
}

Response

• 200 OK: Returns the JSON object of the newly created request, in the same shape as Get single request.
• 400 Bad Request: Returned when a required field is missing or a value fails validation (e.g. an unknown location/contact/tag ID, an invalid enum value, or a min greater than its max). The response body has error_message describing the problem.

Example Response

{
  "status": 200,
  "data": {
    "id": 91,
    "date_created": "2025-06-01 10:00:00",
    "date_updated": "2025-06-01 10:00:00",
    "created_by": 3,
    "store_id": 2,
    "source_id": 1,
    "status": 1,
    "availability": "rent",
    "category": "residential",
    "subcategories": ["apartment"],
    "price_min": null,
    "price_max": 500,
    "size_min": 50,
    "size_max": 70,
    "has_elevator": true,
    "extra_fields": {
      "view": ["sea"],
      "features": ["has_balcony", "has_storage_room"],
      "is_furnished": "yes"
    },
    "contacts": [45],
    "users": [3, 8],
    "tags": [7],
    "locations": [
      {
        "area_level1": 5,
        "area_level2": 12,
        "area_level3": null
      }
    ]
  }
}

Example Error Response

{
  "status": 400,
  "error_message": "Missing contacts"
}

Update request

/api/requests/{id} (PUT)

Edit an existing request. This is a partial update — only the fields included in the JSON body are changed; any field left out keeps its current value.

Important — relation fields are REPLACED, not merged. contacts, locations, subcategories, subtypes, tags, and users, when included in the body, fully replace the existing list rather than being appended to it. To add a contact to a request that already has one, send the full list (existing IDs + the new one).

Request

• Method: PUT
• Headers: Include authentication headers.
• Path Params: The request id to be updated.
• Body: JSON object with only the fields to change. Accepts the same fields as Create request (all optional here, including availability and category), except created_by which cannot be changed.

Notes on partial semantics

• extra_fields, when included, is merged key by key onto the existing extra_fields — a key not present in the extra_fields object you send keeps its previous value. To clear a key, send it as null or an empty array/string (depending on its type).
• Changing category to/from land, or availability to/from shortterm/sale, automatically clears fields that no longer apply (e.g. switching to land clears rooms_min/rooms_max, floor_min/floor_max, has_elevator, and building-only extra_fields keys such as heating_type), even if those specific keys were not part of this request body.
• notes replaces the request's single notes entry; sending an empty string removes it.
• After a successful update, matching against active listings is recalculated automatically.

Example Body

{
  "price_max": 600,
  "extra_fields": {
    "view": ["sea", "mountain"]
  }
}

This example changes only price_max and the view list, leaving every other field (including other extra_fields keys) untouched.

Response

• 200 OK: Returns the JSON object of the updated request, in the same shape as Get single request.
• 400 Bad Request: Returned when a value fails validation. The response body has error_message describing the problem.
• 404 Not Found: Returned when no request exists with the given id.

Example Response

{
  "status": 200,
  "data": {
    "id": 88,
    "date_created": "2025-02-05 11:20:00",
    "date_updated": "2025-06-02 14:30:00",
    "created_by": 3,
    "store_id": 2,
    "source_id": 1,
    "status": 1,
    "availability": "sale",
    "category": "residential",
    "subcategories": ["apartment", "maisonette"],
    "price_min": 100000,
    "price_max": 600,
    "size_min": 70,
    "size_max": 120,
    "rooms_min": 2,
    "rooms_max": 3,
    "has_elevator": false,
    "extra_fields": {
      "view": ["sea", "mountain"]
    },
    "contacts": [23, 45],
    "users": [3, 8],
    "tags": [7, 12],
    "locations": [
      {
        "area_level1": 5,
        "area_level2": 12,
        "area_level3": null
      }
    ]
  }
}

Example Error Response

{
  "status": 404,
  "error_message": "Request not found"
}

Delete request

/api/requests/{id} (DELETE)

Soft-delete a request. The record is marked as deleted and excluded from all future list and single-fetch responses.

Request

• Method: DELETE
• Headers: Include authentication headers.
• Path Params: The request id to be deleted.

Response

• 200 OK: Returns the deleted request ID.

Example Response

{
  "status": 200,
  "deleted_id": 88
}

Get request statuses

/api/requests/statuses (GET)

Fetch the available request statuses.

Request

• Method: GET
• Headers: Include authentication headers.

Response

• 200 OK: Returns a JSON array of available request statuses.

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "Active"
    },
    {
      "id": 2,
      "name": "Inactive"
    }
  ]
}

Get request sources

/api/requests/sources (GET)

Fetch the available request sources.

Request

• Method: GET
• Headers: Include authentication headers.

Response

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

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "Company Website"
    },
    {
      "id": 2,
      "name": "Social Media"
    }
  ]
}

Get request tags

/api/requests/tags (GET)

Fetch the available request tags.

Request

• Method: GET
• Headers: Include authentication headers.

Response

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

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 7,
      "name": "Urgent"
    },
    {
      "id": 12,
      "name": "High Budget"
    }
  ]
}

Get request custom fields

/api/requests/custom-fields (GET)

Fetch the available custom fields for requests.

Request

• Method: GET
• Headers: Include authentication headers.

Response

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

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "Preferred Neighbourhood Notes",
      "type": "textarea"
    },
    {
      "id": 2,
      "name": "Financing Method",
      "type": "select",
      "options": [
        {
          "id": 1,
          "name": "Cash"
        },
        {
          "id": 2,
          "name": "Bank Loan"
        },
        {
          "id": 3,
          "name": "Mixed"
        }
      ]
    }
  ]
}

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.