List Projects

Request

GET /api/v2/clients/projects

Description

Returns a paginated list of projects available to the client.

This is the primary endpoint used to display catalogs, listings, and search results.

The endpoint supports server-side pagination (limit, offset) and accepts multiple query parameters.

Only some filters are currently active on the backend.

Others are declared but do not affect the output yet — the API returns the full dataset regardless of the parameter value.

Response Example

{
  "count": 0,
  "next": "https://api-reelly.up.railway.app/api/v2/clients/projects?limit=5&offset=5",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Project Example",
      "country": "Cyprus",
      "region": "Limassol",
      "status": "Under Construction",
      "sale_status": "On Sale",
      "min_price": 250000,
      "max_price": 450000,
      "cover_image": {
        "url": "https://...",
        "metadata": {
          "mime": "image/webp",
          "size": 18234,
          "width": 1024,
          "height": 768
        }
      },
      "developer": {
        "id": 12,
        "name": "ABC Development"
      }
    }
  ]
}

Query Parameters

The Projects List endpoint provides a flexible set of query parameters that allow external clients to retrieve project data with precision and efficiency.

These parameters support filtering, search, geographic narrowing, unit-level constraints, pricing and area ranges, metadata-driven selections, and pagination.

All parameters are optional and can be freely combined.

Each filter operates independently, and the endpoint returns only the projects that satisfy all provided conditions.

The filtering system supports:

• Project attributes

  Filter by construction status, sale status, update timestamps, or publication state.

• Location-based criteria

  Restrict results by country, region, district, location identifiers, or bounding-box coordinates.

• Unit-level characteristics

  Select projects based on the size, price, bedroom count, or type of their units.

• Search capabilities

  Use free-text search to match project name, developer name, or area name.

• Display preferences

  Choose preferred currency and area units to receive normalized values.

Each query parameter is described in detail in the following sections, including its purpose, data type, supported values, example requests, and notes on expected behavior.

This allows API consumers to construct precise queries tailored to their integration needs while maintaining full compatibility with the current version of the Reelly Clients API.

bounding box filters (map-based filtering)

Description

Bounding box parameters (bbox_ne_lat, bbox_ne_lng, bbox_sw_lat, bbox_sw_lng) define a geographic bounding box for filtering projects by location.

When all required bbox parameters are provided, the API returns only projects located within the specified region.

The box is specified by two corners:

• North-East (top-right) corner:
  • bbox_ne_lat — latitude of the north-east corner
  • bbox_ne_lng — longitude of the north-east corner
• South-West (bottom-left) corner:
  • bbox_sw_lat — latitude of the south-west corner
  • bbox_sw_lng — longitude of the south-west corner

Only projects whose coordinates (latitude, longitude) fall inside this rectangle are returned.

If the rectangle is invalid (for example, the south-west point is “above” or “to the right of” the north-east point, or both corners are identical), the request is still successful, but the response contains zero projects.

This filter is typically used by map-based UIs to load only projects visible in the current viewport.

Meta

Request and Response Examples

Example 1 — Valid bbox that includes “Jacob and Co Beachfront Living”

GET /api/v2/clients/projects
    ?bbox_ne_lat=24.90418233
    &bbox_ne_lng=54.85116912
    &bbox_sw_lat=24.80418233
    &bbox_sw_lng=54.75116912
    &limit=50

Response (truncated):

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "location": {
        "latitude": 24.85418233016819,
        "longitude": 54.80116911866694
      },
      ...
    },
    ...
  ]
}

Example 2 — Valid bbox in a different area (no projects inside)

GET /api/v2/clients/projects
    ?bbox_ne_lat=26.90418233
    &bbox_ne_lng=56.85116912
    &bbox_sw_lat=26.80418233
    &bbox_sw_lng=56.75116912
    &limit=50

Response:

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}

Example 3 — Degenerate or inverted bbox (no results, no error)

GET /api/v2/clients/projects
    ?bbox_ne_lat=24.85418233
    &bbox_ne_lng=54.80116912
    &bbox_sw_lat=24.85418233
    &bbox_sw_lng=54.80116912
    &limit=50

or

GET /api/v2/clients/projects
    ?bbox_ne_lat=24.80418233
    &bbox_ne_lng=54.75116912
    &bbox_sw_lat=24.90418233
    &bbox_sw_lng=54.85116912
    &limit=50

Both return:

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}

Notes

• Parameters like bbox_center_lat / bbox_center_lng are ignored.
• All four parameters must be present for the filter to take effect.
• Partial bbox input behaves like “no bbox filter”.
• Coordinates are expected in standard WGS-84 decimal degrees (the same format as project latitude / longitude).

completion_date_ranges

Description

completion_date_ranges allows clients to filter projects by estimated completion date using one or more UNIX timestamp ranges in UTC. Each range is defined as date_from-date_to, where both boundaries are UNIX timestamps in seconds. Multiple ranges can be provided, separated by commas. A project is included if its completion date falls into at least one of the specified ranges.

This parameter is useful when the consumer needs precise time-based filtering (for example, “all projects with completion date between 1 Jan 2028 and 30 Jun 2028”) without relying on textual quarters or year-only filters.

Meta

Request and Response Examples

Request with a single range (projects completing between 1 Jan 2028 00:00:00 UTC and 30 Jun 2028 23:59:59 UTC):

GET /api/v2/clients/projects?completion_date_ranges=1830297600-1843516799&limit=20

Request with multiple ranges (e.g. early 2028 and late 2028):

GET /api/v2/clients/projects?completion_date_ranges=1830297600-1843516799,1843516800-1856659199&limit=20

Shortened response fragment:

{
  "count": 4,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "completion_date": "Q2 2028",
      "construction_end_date": "2028-03-31",
      "...": "..."
    }
  ]
}

Notes

• Time zone: timestamps must be in UTC and expressed in seconds (standard UNIX time).
• Clients should provide valid date ranges where date_from is earlier than date_to.
• When multiple ranges are provided, a project is included if it matches at least one of them.
• This parameter can be combined with other filters.

completion_quarters

Description

completion_quarters filters projects by declared completion quarter (as used in the project metadata, e.g. “Q2 2028”). Unlike completion_date_ranges, which uses precise timestamps, this parameter works on a higher-level categorical label (quarter + year). It is typically used when the client wants to show inventory grouped by delivery periods (e.g. all projects completing in Q2 2028 or Q3 2028). Multiple quarters can be passed at once to broaden the selection.

Meta

Request and Response Examples

Request for projects completing in Q2 2028 (single quarter label):

GET /api/v2/clients/projects?completion_quarters=Q2%202028&limit=20

Request for multiple quarters (Q2 and Q3 2028):

GET /api/v2/clients/projects?completion_quarters=Q2%202028,Q3%202028&limit=20

Shortened response fragment:

{
  "count": 7,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "completion_date": "Q2 2028",
      "...": "..."
    }
  ]
}

Notes

• Values must match the labels returned by the metadata endpoints (for example, Q2 2028). Clients should always rely on the API responses to obtain the correct values.
• If a value contains spaces, it must be URL-encoded (e.g., Q2 2028 → Q2%202028).
• This parameter can be used together with other filters such as country, region, or price-based filters.
• If used together with other completion-related filters, all provided filters will be applied. Clients should specify only the filters they intend to use.

country

Description

Filters the project list by country name. When this parameter is provided, only projects located in the specified country are returned. The value must match one of the country names returned by the Countries endpoint (for example, "United Arab Emirates", "Cyprus", "Indonesia", "Oman", "Thailand"). This parameter is typically used together with regional filters (such as region or districts) to narrow the search to a specific market.

Meta

Request and Response Examples

Filter projects in the United Arab Emirates:

GET /api/v2/clients/projects?country=United%20Arab%20Emirates&limit=20

Possible response fragment:

{
  "count": 125,
  "next": "...",
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "location": {
        "country": "United Arab Emirates",
        "region": "Abu Dhabi Emirate",
        "district": "Ghadeer Al Tayr"
      }
      // ...
    }
  ]
}

Filter projects in Cyprus:

GET /api/v2/clients/projects?country=Cyprus&limit=20

Notes

• Allowed values for country are exactly those returned by:

  GET /api/v2/clients/countries

• Values with spaces must be URL-encoded (for example, United Arab Emirates → United%20Arab%20Emirates).

• Can be combined with other filters such as region, districts, price range, construction_status, sale_status, and bounding box parameters.

created (to describe)

developer

Description

Filters the project list by developer. When this parameter is set, only projects associated with the specified developer are returned. The value should correspond to the internal identifier of a developer used across the platform (for example, the ID used in the Developers list/details APIs and in project metadata). This filter allows clients to build views such as “all current projects of a particular developer”.

Meta

Request and Response Examples

Filter projects of a specific developer:

GET /api/v2/clients/projects?developer=45&limit=20

Response (fragment):

{
  "count": 8,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "developer": "Ohana Developments"
      // ...
    }
  ]
}

Notes

• The value must match a valid developer identifier from the Developers metadata.
• Can be combined with geographic filters (country, region, districts) and commercial filters (price range, construction status, sale status) to create precise listings.

districts

Description

Filters the project list by one or several districts. This parameter lets the client restrict results to specific subareas (for example, particular neighborhoods within a city or emirate). Multiple districts can be provided in a single request so that projects belonging to any of the specified districts are included. This is especially useful for map-based search and location-focused pages.

Meta

Request and Response Examples

Filter projects in a single district:

GET /api/v2/clients/projects?districts=271&limit=20

Filter projects in multiple districts:

GET /api/v2/clients/projects?districts=271,135,412&limit=20

Response (fragment):

{
  "count": 12,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "location": {
        "district": "Ghadeer Al Tayr",
        "id": 271
      }
      // ...
    }
  ]
}

Notes

• Each value should correspond to a valid district identifier from the Districts metadata.
• When multiple IDs are provided, a project is included if it belongs to any of the specified districts.
• Can be freely combined with country, region, price filters, and other parameters of the endpoint.

has_escrow

Description

Filters the list of projects by whether they are associated with an escrow account.

When used in the Projects list endpoint, this parameter narrows the result set to projects that either do or do not have escrow according to the project’s configuration in the system.

The parameter affects only the filtering logic of the /projects list response and is not included as a field in that response.

To see escrow-related details (such as escrow number), the client has to call the Project details endpoint for a specific project.

Meta

Request and Response Examples

Request (filter projects that have escrow):

GET /api/v2/clients/projects?has_escrow=true&limit=20

Response (fragment, without escrow fields in the list):

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1147,
      "name": "Example Project With Escrow",
      "location": { "country": "United Arab Emirates", "region": "Dubai Emirate" },
      "construction_status": "under_construction",
      "sale_status": "on_sale"
      // ... other list fields, but no escrow field here
    }
  ]
}

To inspect escrow details of a specific project (separate endpoint):

GET /api/v2/clients/projects/1147

Response (fragment with escrow-related data on details level):

{
  "id": 1147,
  "name": "Example Project With Escrow",
  "has_escrow": true,
  "buildings": [
    {
      "id": 2001,
      "name": "Tower A",
      "escrow": "1234567890"
      // ...
    }
  ]
  // ...
}

Notes

• has_escrow=true returns only projects that are configured in the system as having escrow.
• has_escrow=false returns only projects that are configured as not having escrow.
• If has_escrow is not provided, projects are not filtered by escrow and all matching projects are returned according to other filters.
• Escrow details are available only in the Project details response, not in the Projects list response.

language

The language parameter specifies the language used for translatable text fields returned by the List Projects endpoint.

When provided, the API returns all supported translatable text fields in the requested language. If a translation is not available for a specific field, the API falls back to English (en-us) without error.

The parameter affects only the representation of text values in the response. It does not influence filtering, sorting, pagination, currency conversion, or area unit conversion.

Translatable fields

For the List Projects endpoint, the language parameter applies to the following fields:

Note: Status fields (construction_status, sale_status) are always returned in snake_case English (completed, under_construction, on_sale) regardless of the language parameter.

Supported languages

Available language codes:

GET /api/v2/clients/projects/languages

Confirmed languages with translated content: en-us (default), ar, de, fr, he, hi, it, pl, ru, tr, zh.

Filtering with translated values

The status and sale_status filter parameters accept values in any supported language when language is specified. The general pattern:

GET /api/v2/clients/projects?language={code}&status={translated_value}
GET /api/v2/clients/projects?language={code}&sale_status={translated_value}

To retrieve the list of accepted values for a given language:

GET /api/v2/clients/projects/statuses?language={code}
GET /api/v2/clients/projects/sale-statuses?language={code}

Note: Regardless of the filter value used, construction_status and sale_status in the response are always returned in snake_case English (completed, under_construction, on_sale).

Meta

Request and Response Examples

Example 1 — French, filter by status, translated value:

GET /api/v2/clients/projects?language=fr&status=Achevé&limit=1

Response (fragment):

{
  "results": [
    {
      "id": 1,
      "name": "Amalia Residences",
      "overview": "Faits généraux du projet...",
      "construction_status": "completed",
      "sale_status": "out_of_stock"
    }
  ]
}

Example 2 — German, filter by sale status, translated value:

GET /api/v2/clients/projects?language=de&sale_status=Im+Verkauf&limit=1

Response (fragment):

{
  "results": [
    {
      "id": 12,
      "name": "One Crescent Palm",
      "overview": "Projektinformationen...",
      "construction_status": "under_construction",
      "sale_status": "on_sale"
    }
  ]
}

Example 3 — Default behavior (parameter omitted):

GET /api/v2/clients/projects?limit=1

Response (fragment):

{
  "results": [
    {
      "id": 1,
      "name": "Amalia Residences",
      "overview": "Project general facts. Amalia Residences is a prestigious mid-rise residential tower...",
      "construction_status": "completed",
      "sale_status": "out_of_stock"
    }
  ]
}

Notes

• Supported language codes are available at GET /api/v2/clients/projects/languages.
• construction_status and sale_status in the response are always returned in snake_case English, regardless of language.
• Filter parameters status and sale_status accept both English values (completed, Under Construction) and translated values (Achevé, Im Bau) when language is set.
• Fields without available translations fall back to English silently.

post_handover

Filters the list of projects by whether they offer post-handover payment options.

When this parameter is used in the Projects list endpoint, the server returns only projects whose payment plans are marked as post-handover (for example, where part of the payment is scheduled after the handover date).

Similar to has_escrow, the post_handover parameter only affects filtering and is not included as a field in the /projects list response.

Information about post-handover payment plans can be retrieved via the Project details endpoint, which exposes detailed payment plan configuration per project.

Meta

Request and Response Examples

Request (filter projects with post-handover payment options):

GET /api/v2/clients/projects?post_handover=true&limit=20

Response (fragment, without post_handover field in the list):

{
  "count": 7,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "construction_status": "presale",
      "sale_status": "on_sale"
    }
  ]
}

Details of a specific project with post-handover payment plan:

GET /api/v2/clients/projects/2211

Response (fragment with payment plans):

{
  "id": 2211,
  "name": "Jacob and Co Beachfront Living",
  "post_handover": false,
  "payment_plans": [
    {
      "id": 2052,
      "name": "Payment Plan for Villas and Mansions",
      "is_handover": false,
      "steps": [
        {
          "name": "On booking",
          "percentage": 5.0
        },
        {
          "name": "On signing SPA",
          "percentage": 20.0
        },
        {
          "name": "After signing the SPA for 3 years (6.25% every 3 months)",
          "percentage": 75.0
        }
      ]
    }
  ]
}

Notes

• post_handover=true returns only projects that have post-handover payment terms in the system (part of payments after handover).
• post_handover=false returns projects without post-handover options.
• If the parameter is not specified, there is no post-handover filtering; only the other filters are applied.
• The detailed structure of payment plans is available in Project details; the parameter is not displayed in the project list, it is only used for filtering.

Syntax Example

GET /api/v2/clients/projects?country=Cyprus&region=Dubai&location_ids=301,302&status=Under%20Construction&sale_status=On%20Sale

Notes

• Allowed values should be obtained from metadata endpoints:

  /projects/countries, /projects/regions, /projects/locations, /projects/statuses, /projects/sale-statuses.

• Parameters are optional and may be combined.

pagination

Request

GET /projects?limit=5&offset=0

Pagination Parameters

• limit — (optional, integer)

  Maximum number of projects to return in a single response.

• offset — (optional, integer)

  Number of projects to skip before starting to collect the result set.

Response Structure

• If no limit is provided, the default page size is 20 items.
• The count field returns the total number of projects available to the client.
• The next and previous fields contain URLs for navigating between pages (or null if there is no next/previous page).
• Pagination can be safely combined with sorting.

Response Example (simplified)

{
  "count": 0,
  "next": "https://api-reelly.up.railway.app/api/v2/clients/projects?limit=5&offset=5",
  "previous": null,
  "results": [
    {
      "id": 128,
      "name": "Canal Heights",
      "developer": "DAMAC",
      "construction_status": "under_construction",
      "sale_status": "on_sale",
      "min_price": 2827999.994625,
      "max_price": 17542999.9875,
      "min_size": 948.5274857198399,
      "max_size": 4381.16457587796,
      "price_currency": "AED",
      "area_unit": "sqft",
      "units_count": 48,
      "readiness_progress": 13.37,
      "location": {
        "id": 641,
        "country": 219,
        "region": "Dubai",
        "city": null,
        "district": "Business Bay",
        "sector": "Business Bay",
        "village": null,
        "latitude": 25.183638,
        "longitude": 55.278551
      },
      "cover_image": {
        "url": "https://api.reelly.io/vault/ZZLvFZFt/ZNIiE9EN7ACufoA0rYkcdC8AT1M/We3V0A../WhatsApp+Image+2023-02-17+at+17_49_43+%281%29.jpeg",
        "metadata": {
          "mime": "image/jpeg",
          "size": 288715,
          "width": 1600,
          "height": 1131
        }
      },
      "is_partner_project": false,
      "status": "under_construction"
    }
  ]
}

Typical Use Cases

• Building search results for catalog pages
• Filtering by country or region
• Filtering by district/sector via location_ids
• Filtering by sale status or development status
• Displaying project lists synchronized with a map

Example usage

GET /api/v2/clients/projects?country=Cyprus
GET /api/v2/clients/projects?region=Dubai
GET /api/v2/clients/projects?location_ids=300,302
GET /api/v2/clients/projects?status=Under%20Construction

Notes

• Response can be large. Pagination is implemented.
• Filtering is reliable and based only on what metadata endpoints expose.
• All fields in the example above come from real responses.

preferred_area_unit

Description

Specifies the measurement unit used for area values in the /projects list response (area_unit, min_size, max_size).

The API accepts several values, but converts numbers only when the value is m2.

Behavior confirmed by testing:

• sqft — values are returned in square feet.
• m2 — values are returned in square meters (conversion applied).
• Any other value (for example, sqm, meter) is accepted without error, and:
  • the numeric values are returned as square feet
  • the string returned in area_unit matches the input (for example, sqm)

If the parameter is not provided, the API defaults to square feet.

Meta

Request and Response Examples

1. Using preferred_area_unit=sqft

   GET /api/v2/clients/projects?preferred_area_unit=sqft&limit=1

   Response fragment:

   JSON

   {
     "area_unit": "sqft",
     "min_size": 1167.6792152516398,
     "max_size": 5033.66972540796
   }

2. Using preferred_area_unit=m2

   GET /api/v2/clients/projects?preferred_area_unit=m2&limit=1

   Response fragment:

   JSON

   {
     "area_unit": "m2",
     "min_size": 108.48004601,
     "max_size": 467.63932789
   }

   (Numeric values converted from square feet to square meters.)

3. Using a non-standard value, for example preferred_area_unit=sqm

   GET /api/v2/clients/projects?preferred_area_unit=sqm&limit=1

   Response fragment:

   JSON

   {
     "area_unit": "sqm",
     "min_size": 1167.6792152516398,
     "max_size": 5033.66972540796
   }

   The returned values correspond to square feet, even though the unit label reflects the input.

Notes

• Recommended values for integrations:
  • sqft — for square feet
  • m2 — for square meters (with actual conversion)
• Any other value is accepted but behaves like sqft internally.
• Safe to combine with any other filters.

preferred_currency

Description

Specifies the currency in which project prices (min_price, max_price, and price_currency) are returned by the endpoint.

The parameter does not change which projects are selected; it changes only the currency and numeric values of prices in the response.

In the current public API contract, only AED and USD are documented as supported values. Passing other values is not supported and may result in a server error (for example, preferred_currency=ABC returns HTTP 500).

Meta

Request and Response Examples

Example 1 — Prices in AED (base currency)

Request:

GET /api/v2/clients/projects?preferred_currency=AED&limit=20

Response (fragment):

{
  "count": 123,
  "next": "...",
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "price_currency": "AED",
      "min_price": 4011000.017375,
      "max_price": 20166999.98885
    }
  ]
}

Example 2 — Prices in USD

Request

GET /api/v2/clients/projects?preferred_currency=USD&limit=20

Response (fragment)

{
  "count": 123,
  "next": "...",
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "price_currency": "USD",
      "min_price": 1092171.55,
      "max_price": 5491354.66
    }
  ]
}

Example 3 — Unsupported value (error)

Request:

GET /api/v2/clients/projects?preferred_currency=ABC&limit=20

Response (fragment):

{
  "detail": "Server Error (500)"
}

Notes

• The parameter controls only the currency representation of price fields; filtering and the set of returned projects remain the same in tested requests, regardless of whether AED or USD is used.
• Supported values in this documentation:
  • AED — prices returned in United Arab Emirates dirhams
  • USD — prices returned in US dollars
• Any other value is treated as unsupported and may lead to an HTTP 500 response (for example, preferred_currency=ABC).

price_type

Description

Specifies how the project price range filter should be interpreted in combination with unit_price_from and unit_price_to. When set to unit, the API treats the price range as the total price of a unit (for example, full apartment or villa). When set to area, the API treats the price range as price per area unit (for example, per square foot or per square meter, depending on preferred_area_unit). This allows clients to search either by total ticket size or by price per square unit, using the same numeric range parameters.

Meta

Request and Response Examples

Request: filter by total unit price (default behavior, equivalent to omitting price_type)

GET /api/v2/clients/projects?unit_price_from=2000000&unit_price_to=4000000&price_type=unit&limit=20

Request: filter by price per area unit (for example, per m² or per sqft, depending on preferred_area_unit)

GET /api/v2/clients/projects?unit_price_from=2000&unit_price_to=4000&price_type=area&preferred_area_unit=m2&limit=20

Response (fragment, typical project list structure)

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "min_price": 3044499.0,
      "max_price": 82499999.99,
      "price_currency": "AED",
      "min_size": 548.96,
      "max_size": 23196.41,
      "area_unit": "sqft",
      "...": "..."
    }
  ]
}

Notes

• Allowed values:
  • unit — treat unit_price_from / unit_price_to as total unit price
  • area — treat unit_price_from / unit_price_to as price per area unit (per preferred_area_unit)
• If price_type is omitted, the API behaves as if price_type=unit is used.
• price_type should always be used together with unit_price_from and/or unit_price_to; by itself it does not apply any price filter.
• It’s good practice on the client side to:
  • clearly label filters in the UI (for example, “Total price” vs. “Price per m²”)
  • ensure that entered values match the interpretation selected via price_type

project_ids

Description

Allows filtering the project list by explicitly specifying one or multiple project identifiers. This parameter is useful when the client already knows the IDs of target projects (for example, from saved lists, search indices, or external systems) and wants to retrieve only those entries. The parameter accepts a comma-separated list of numeric IDs. If any of the IDs do not exist or do not match published projects, they are ignored. If none of the provided IDs are valid, the API returns an empty result set.

The filter operates independently of other parameters and can be combined with additional filters (for example, country, region, sale_status), though the result will include only projects matching all applied conditions.

Meta

Request and Response Examples

Request (multiple project IDs):

GET /api/v2/clients/projects?project_ids=2211,1147,500&limit=20

Request (single ID):

GET /api/v2/clients/projects?project_ids=2211

Response (fragment):

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "min_price": 1720557.99,
      "max_size": 23196.41,
      "area_unit": "sqft"
    }
  ]
}

Notes

• IDs must be numeric.
• Unknown or unpublished project IDs are silently ignored.
• When combined with other filters, only intersections are returned.
• Useful for restoring user selections or syncing with external catalogs.

region

Description

Filters projects by the region in which they are located. The parameter accepts a text value matching one of the region names published by the /clients/regions endpoint. Filtering is case-insensitive but must match the canonical string value. If a region is provided that does not exist in the system, the API returns an empty result set.

This filter is commonly used to limit results within major administrative divisions such as Dubai Emirate or Abu Dhabi Emirate.

The region filter can be combined with other geographical parameters such as country, districts, and bounding box filters.

Meta

Request and Response Examples

Get list of valid regions:

GET /api/v2/clients/regions

Example response:

[
  "Dubai Emirate",
  "Abu Dhabi Emirate",
  "Ras Al Khaimah",
  "Sharjah"
]

Filter projects by region:

GET /api/v2/clients/projects?region=Abu%20Dhabi%20Emirate&limit=20

Response (fragment):

{
  "count": 37,
  "results": [
    {
      "id": 2211,
      "name": "Jacob and Co Beachfront Living",
      "location": {
        "region": "Abu Dhabi Emirate",
        "...": "..."
      }
    }
  ]
}

Notes

• Must use exact region names from metadata.
• URL-encode spaces when necessary (Abu Dhabi Emirate → Abu%20Dhabi%20Emirate).
• If combined with country, region must belong to that country.

sale_status

Description

Filters the projects list by the current sale status. The parameter accepts both human-readable values (for example, On Sale, Out of Stock) and their snake_case equivalents (for example, on_sale, out_of_stock). Returned project objects always use snake_case in the sale_status field.

Meta

Allowed values

Request and Response Examples

GET /api/v2/clients/projects?sale_status=On%20Sale

Response (truncated):

{
  "count": 123,
  "next": "https://api-reelly.up.railway.app/api/v2/clients/projects?sale_status=On%20Sale&limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Sample Project",
      "developer": "Sample Developer",
      "construction_status": "under_construction",
      "sale_status": "on_sale",
      "location": {
        "id": 382,
        "region": "Dubai",
        "district": "Al Furjan",
        "latitude": 25.0189777,
        "longitude": 55.1441793
      },
      "min_price": 0,
      "max_price": 0,
      "price_currency": "AED",
      "area_unit": "sqft",
      "is_published": true
    }
  ]
}

Notes

• The sale_status filter accepts both human-readable values and their snake_case equivalents.
• Project objects always return sale status values in snake_case format.
• Both ?sale_status=On%20Sale and ?sale_status=on_sale return identical results.
• Returned project data always uses the canonical snake_case form.

search_query

Description

Performs a free-text search across key project attributes.

The search is case-insensitive and uses substring matching.

Results include projects where the query matches any of the following fields:

• project name
• developer name
• area name (location’s region or district)

Meta

Request and Response Examples

GET /api/v2/clients/projects?search_query=Beach

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 501,
      "name": "Beachfront Residences",
      "developer": "Example Developer",
      "construction_status": "under_construction",
      "sale_status": "on_sale",
      "location": {
        "id": 100,
        "region": "Dubai",
        "district": "Dubai Harbour",
        "latitude": 25.089,
        "longitude": 55.144
      },
      "price_currency": "AED",
      "area_unit": "sqft",
      "is_published": true
    }
  ]
}

Notes

• Matches are performed against the project name, developer name, and area name.
• Search is case-insensitive and supports partial (substring) matches.
• Can be used in combination with any other filter.

status

Description

Filters the projects list by construction status.

The parameter accepts both human-readable values (such as Under Construction) and their snake_case equivalents (such as under_construction).

Projects returned by the endpoint always expose the construction stage in the construction_status field using the canonical snake_case format.

Meta

Allowed values

Request and Response Examples

GET /api/v2/clients/projects?status=Under%20Construction

{
  "count": 10,
  "next": "https://api-reelly.up.railway.app/api/v2/clients/projects?status=Under%20Construction&limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 1120,
      "name": "7 Sens Villas",
      "developer": "7 Sens",
      "construction_status": "under_construction",
      "sale_status": "out_of_stock",
      "location": {
        "id": 312,
        "region": "Bali",
        "district": "Gianyar",
        "latitude": -8.490058656406216,
        "longitude": 115.28299172436508
      },
      "min_price": 0,
      "max_price": 0,
      "price_currency": "AED",
      "area_unit": "sqft",
      "is_published": true
    }
  ]
}

Notes

• The status parameter supports both human-readable and snake_case input formats.
• Regardless of input format, returned project objects always use snake_case in the construction_status field.
• Both status=Under%20Construction and status=under_construction produce equivalent filtering behavior.

unit_area_from

Description

Filters the projects list by the minimum unit area.

A project is included if its min_size value is greater than or equal to the specified threshold.

The comparison respects the preferred_area_unit parameter when provided.

Meta

Request and Response Examples

GET /api/v2/clients/projects?unit_area_from=500

{
  "count": 42,
  "results": [
    {
      "id": 501,
      "name": "Beachfront Residences",
      "min_size": 520,
      "max_size": 2000,
      "area_unit": "sqft"
    }
  ]
}

Notes

• The comparison is performed against the project-level field min_size.
• Projects where min_size meets or exceeds the specified value are included.
• Area interpretation follows preferred_area_unit; when omitted, the unit defaults to sqft.

unit_area_to

Description

Filters the projects list by the maximum unit area.

A project appears in results if its max_size value is less than or equal to the specified threshold.

The comparison uses the unit system defined by preferred_area_unit when provided.

Meta

Request and Response Examples

GET /api/v2/clients/projects?unit_area_to=1200

{
  "count": 18,
  "results": [
    {
      "id": 777,
      "name": "Skyline Towers",
      "min_size": 650,
      "max_size": 1180,
      "area_unit": "sqft"
    }
  ]
}

Notes

• The filter uses the project-level field max_size.
• Projects are included if their max_size value is less than or equal to the given limit.
• Unit conversion behavior is defined by preferred_area_unit.

unit_bedrooms

Description

Filters the project list based on the number of bedrooms available in the units of each project.

A project appears in the result set if any of its units (including entries in typical_units) has a bedroom count matching one of the values specified in unit_bedrooms.

The parameter accepts:

• integer values (for example, 0, 1, 2, 3, 5, 11)
• decimal values when present in the data (for example, 1.5)
• multiple values, comma-separated (evaluated as logical OR)

Examples:

• unit_bedrooms=0 → returns projects offering studio units
• unit_bedrooms=1,2 → returns projects offering 1-bedroom or 2-bedroom units
• unit_bedrooms=1.5 → returns projects offering fractional bedroom units

This filter applies to underlying project unit inventory, even though the List Projects response does not include unit-level bedroom information.

Meta

Request and Response Examples

Filter projects offering studio units (0 bedrooms):

GET /api/v2/clients/projects?unit_bedrooms=0&limit=20

Filter projects offering 1-bedroom units:

GET /api/v2/clients/projects?unit_bedrooms=1&limit=20

Example response (fragment):

{
  "count": 276,
  "next": "https://api-reelly.up.railway.app/api/v2/clients/projects?unit_bedrooms=0&limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 2291,
      "name": "Example Project",
      "developer": "Example Developer",
      "construction_status": "under_construction",
      "sale_status": "on_sale",
      "overview": "...",
      "location": {
        "id": 100,
        "country": 219,
        "region": "Dubai",
        "district": "Arjan",
        "latitude": 25.0559,
        "longitude": 55.2399
      },
      "min_price": 1299000.0,
      "max_price": 4200000.0,
      "min_size": 410.0,
      "max_size": 980.0,
      "price_currency": "AED",
      "area_unit": "sqft",
      "is_published": true,
      "cover_image": {
        "url": "https://api.reelly.io/vault/...",
        "metadata": {
          "mime": "image/jpeg",
          "size": 147045,
          "width": 849,
          "height": 600
        }
      }
    }
  ]
}

Filter projects offering 1 or 5 bedrooms:

GET /api/v2/clients/projects?unit_bedrooms=1,5&limit=20

Filter projects offering fractional bedroom values, when present:

GET /api/v2/clients/projects?unit_bedrooms=1.5&limit=20

Notes

• Multiple values are evaluated as logical OR.
• The filter supports both integer and decimal bedroom values when such values exist in unit data.
• If none of the specified bedroom counts exist in project units, the API returns an empty result set.
• This parameter can be combined with any other filters, including price ranges, unit types, location filters, construction status, sale status, etc.
• Bedroom matching is performed against the project’s unit inventory; the List Projects response does not include bedroom information directly.

unit_price_from

Description

Filters projects by the minimum unit price.

A project is included if its min_price value is greater than or equal to the specified amount.

When preferred_currency is provided, the comparison uses the converted value in that currency.

Meta

Request and Response Examples

GET /api/v2/clients/projects?unit_price_from=2000000

{
  "count": 57,
  "results": [
    {
      "id": 1120,
      "name": "7 Sens Villas",
      "min_price": 2000000,
      "max_price": 6400000,
      "price_currency": "AED"
    }
  ]
}

Notes

• Comparison is made against the project-level min_price field.
• Projects are included when min_price is equal to or higher than the provided threshold.
• When preferred_currency is used, the input value and the project prices are evaluated in the selected currency.

unit_price_to

Description

Filters projects by the maximum unit price.

A project is included if its max_price value is less than or equal to the specified amount.

Currency conversion is applied automatically when preferred_currency is used.

Meta

Request and Response Examples

GET /api/v2/clients/projects?unit_price_to=1500000

{
  "count": 21,
  "results": [
    {
      "id": 88,
      "name": "Palm Oasis",
      "min_price": 980000,
      "max_price": 1480000,
      "price_currency": "AED"
    }
  ]
}

Notes

• Filtering uses the project-level max_price field.
• Projects are included when max_price does not exceed the specified value.
• If preferred_currency is provided, all price values are compared in that currency.

unit_types

Description

Filters the projects list by the types of units available in each project.

The parameter accepts a single unit type value per request, using one of the values returned by the unit types metadata endpoint:

GET /api/v2/clients/units/types

Meta

Allowed values

The following values are returned by the unit types metadata endpoint and can be used with the unit_types filter:

Request and Response Examples

GET /api/v2/clients/projects?unit_types=Apartments

{
  "count": 37,
  "next": "https://api-reelly.up.railway.app/api/v2/clients/projects?unit_types=Apartments&limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 300,
      "name": "Harbour Residences",
      "developer": "Example Developer",
      "units_count": 120,
      "min_price": 1200000,
      "max_price": 4200000,
      "price_currency": "AED",
      "min_size": 650,
      "max_size": 1800,
      "area_unit": "sqft",
      "is_published": true
    }
  ]
}

Notes

• The unit_types parameter uses the same value set as the GET /api/v2/clients/units/types metadata endpoint.
• It is recommended to pass values exactly as returned by the metadata endpoint.
• The filter includes projects that offer at least one unit of the specified type.

updated_at_after

Description

Filters the projects list and returns only projects whose updated_at value is later than or equal to the specified timestamp.

The parameter accepts an ISO-8601 datetime string.

Meta

Request and Response Examples

GET /api/v2/clients/projects?updated_at_after=2025-01-01T00:00:00Z

{
  "count": 84,
  "next": "https://api-reelly.up.railway.app/api/v2/clients/projects?updated_at_after=2025-01-01T00:00:00Z&limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 1120,
      "name": "7 Sens Villas",
      "updated_at": "2025-10-03T18:17:37.514542Z",
      "construction_status": "under_construction",
      "sale_status": "out_of_stock",
      "price_currency": "AED",
      "area_unit": "sqft",
      "is_published": true
    }
  ]
}

Notes

• The filter includes projects with updated_at timestamps greater than or equal to the specified value.
• The parameter must be passed in a standard ISO-8601 datetime format (for example, 2025-01-01T00:00:00Z).
• Timezone information should be included; values without timezone are interpreted according to the server’s default.

updated_at_before

Description

Filters the projects list and returns only projects whose updated_at value is earlier than or equal to the specified timestamp.

The parameter accepts an ISO-8601 datetime string.

Meta

Request and Response Examples

GET /api/v2/clients/projects?updated_at_before=2025-05-01T00:00:00Z

{
  "count": 310,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 501,
      "name": "Beachfront Residences",
      "updated_at": "2025-04-12T14:22:10.901233Z",
      "construction_status": "under_construction",
      "sale_status": "on_sale",
      "price_currency": "AED",
      "area_unit": "sqft",
      "is_published": true
    }
  ]
}

Notes

• The filter includes projects with updated_at timestamps less than or equal to the specified value.
• Accepts timestamps in standard ISO-8601 format.
• Works independently or in combination with updated_at_after to define a date range.