---
title: "Search alerts (v1)"
method: POST
path: "/api/v1/listing-alerts/search"
tags: ["api---alerts"]
---

# Search alerts (v1)

`POST /api/v1/listing-alerts/search`

## Request

- Base URL: `https://api.casafari.com`
- URL: `https://api.casafari.com/api/v1/listing-alerts/search`
- Auth: HTTP bearer

Returns paginated list of alerts (by requested parameters) for currently authenticated user.

## Query parameters

- `limit` integer
- `offset` integer
- `order_by` 'alert_date' | '-alert_date' | 'alert_id' | '-alert_id' | 'created_at' | '-created_at' | 'updated_at' | '-updated_at'
- `alert_subtype` 'new' | 'price_up' | 'price_down' | 'reserved' | 'delisted' | 'sold'

## Request body

- ApiAlertsSearchFilterV1
  - `operation` 'sale' | 'rent', required: Operation type.
  - `location_ids` integer[]: List of location IDs, as returned by the [POST /api/v1/references/locations](/#operation/api__post__v1__references__locations) endpoint.
  - `custom_location` object[]: Closed polygon of geo-points to search within. First and last points must match.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `custom_locations` field instead.</strong>
    - `latitude` number, required: Latitude.
    - `longitude` number, required: Longitude.
  - `custom_locations` array[]: List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed.
    - object[]
      - `latitude` number, required: Latitude.
      - `longitude` number, required: Longitude.
  - `types` string[]: <br>Country availability per type is available at the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.<br><br>Property types by type groups:<br/><strong>apartment:</strong> penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex<br/><strong>house:</strong> townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (<span style="color:red">DEPRECATED</span>), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house<br/><strong>room:</strong> room<br/><strong>building:</strong> office_building, apartment_building, mix_use_building<br/><strong>investment:</strong> retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt<br/><strong>plot:</strong> rural_plot, urban_plot, plot (<span style="color:red">DEPRECATED</span>)<br/><strong>other:</strong> garage, other, parking
  - `conditions` string[]: Property conditions, as returned by the [GET /api/v1/references/conditions](/#operation/api__get__v1__references__conditions) endpoint.
  - `alert_date_from` string, date: Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest.
  - `alert_date_to` string, date: End date (in the format `YYYY-MM-DD`) of the period for alerts of interest.
  - `created_at_from` string, date-time: Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data.
  - `created_at_to` string, date-time: End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data.
  - `created_at_with_photos_from` string, date-time: Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any.
  - `created_at_with_photos_to` string, date-time: End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any.
  - `statuses` string[]: Current status of the listing.
  - `price_from` integer: Minimum price value.
  - `price_to` integer: Maximum price value.
  - `price_per_sqm_from` integer: Minimum value for price per square meter.
  - `price_per_sqm_to` integer: Maximum value for price per square meter.
  - `bedrooms_from` integer: Minimum number of bedrooms.
  - `bedrooms_to` integer: Maximum number of bedrooms.
  - `bathrooms_from` integer: Minimum number of bathrooms.
  - `bathrooms_to` integer: Maximum number of bathrooms.
  - `total_area_from` integer: Minimum total area.
  - `total_area_to` integer: Maximum total area.
  - `plot_area_from` integer: Minimum plot area.
  - `plot_area_to` integer: Maximum plot area.
  - `construction_year_from` integer: Minimum construction year.
  - `construction_year_to` integer: Maximum construction year.
  - `floor` 'no_floor' | 'ground' | 'middle' | 'top': Floor type. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `floors` field instead.</strong>
  - `floors` string[]: List of floor types.
  - `orientation` 'exterior' | 'interior': Property view orientation.
  - `view` 'water' | 'landscape' | 'city' | 'golf' | 'park': View from the property. "<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `views` field instead.</strong>"
  - `views` string[]: List of views from the property.
  - `direction` 'north' | 'south' | 'east' | 'west': Cardinal direction the property faces. "<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `directions` field instead.</strong>
  - `directions` string[]: List of cardinal directions the property faces.
  - `characteristics` string[]: Property characteristics.
  - `alert_subtypes` string[]: Alert subtypes.
  - `private` boolean: Whether to return alerts only from properties listed by a private individual, as opposed to an agent or a professional.
  - `auction` boolean: Whether to return alerts from auction property listings.
  - `bank` boolean: Whether to return alerts from bank property listings.
  - `new_development` boolean: Whether to return alerts from new development property listings.
  - `listing_agents` string[]: Return alerts only for properties from specified agents. To find allowed agent names use the [GET /api/v1/references/agents](/#operation/api__get__v1__references__agents) endpoint.
  - `with_agencies` string[]: Return alerts only for properties from specified agencies, companies or sources. To find allowed agency names use the [GET /api/v1/references/agencies](/#operation/api__get__v1__references__agencies) endpoint.
  - `without_agencies` string[]: Exclude alerts for properties from specified agencies, companies or sources. To find allowed agency names use the [GET /api/v1/references/agencies](/#operation/api__get__v1__references__agencies) endpoint.
  - `exclusive` boolean: Whether to return alerts exclusively from specific listings rather than from all related to the property listings.<br/>Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`.
  - `ref_numbers` string[]: List of reference numbers from listings.
  - `has_phone` boolean: Whether to return alerts only from listings with or without `phone` number.
  - `has_email` boolean: Whether to return alerts only from listings with or without email.
  - `has_agency_name` boolean: Whether to return alerts only from listings with or without agency name.
  - `property_ids` integer[]: List of property IDs.
  - `listing_ids` integer[]: List of listing IDs.

## Response `200`

- object[]
  - `count` integer
  - `next` string, uri, nullable
  - `previous` string, uri, nullable
  - `results` ApiAlertDocumentsV1
    - `alert_id` integer, required: ID of the alert.
    - `listing_id` integer, required: ID of the listing (ad).
    - `ref` string, required: The reference ID of the listing.
    - `alert_type` 'sale_price' | 'sale_status' | 'rent_price' | 'rent_status' | 'new', required: The type of the alert.
    - `alert_subtype` 'new' | 'price_up' | 'price_down' | 'reserved' | 'delisted' | 'sold', nullable, required: The subtype of the alert.
    - `old_value` string, required: Value before change.
    - `new_value` string, required: Value after change.
    - `alert_date` string, date, required: Date when the alert occurred.
    - `alert_date_and_time` string, nullable: Date and time when the alert occurred.
    - `property_url` string, nullable: URL of the property in the CASAFARI website.
    - `listing_url` string, nullable: URL of the listing. Available only for currently active listings.
    - `listing_old_url` string, nullable: Old URL of the listing. Available only for currently inactive listings.
    - `listing_uid` string, required: Unique ID of the listing on the source site.
    - `property_id` integer, required: ID of the property to which the listing belongs.
    - `title` string, required: Listing title.
    - `type` 'apartment' | 'studio' | 'duplex' | 'penthouse' | 'dachgeschosswohnung' | 'etagenwohnung' | 'erdgeschosswohnung' | 'country_house' | 'house' | 'palace' | 'townhouse' | 'villa' | 'country_estate' | 'chalet' | 'bungalow' | 'family_house' | 'reihenhaus' | 'reihenendhaus' | 'reihenmittelhaus' | 'einfamilienhaus' | 'zweifamilienhaus' | 'landwirtschaftliche_betriebe' | 'retail' | 'office' | 'industrial' | 'warehouse' | 'hotel' | 'other_commercial' | 'restaurant' | 'werkstatt' | 'plot' | 'urban_plot' | 'rural_plot' | 'room' | 'other' | 'garage' | 'parking' | 'apartment_building' | 'office_building' | 'mix_use_building', required: Listing property type, as returned by the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.
    - `type_group` string, required: Listing property type group, as returned by the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.
    - `location` object, required: Information about property location.
      - `location_id` integer, required: ('Location ID, as returned by the [POST /api/v1/references/locations](/#operation/api__post__v1__references__locations) endpoint.',)
      - `name` string, required: Location name.
      - `administrative_level` string, required: Location administrative level.
      - `zip_codes` string[]: The location zip codes.
    - `locations_structure` object[], required: Information about all the parent locations (including property location) up to the country.
      - `location_id` integer, required: ('Location ID, as returned by the [POST /api/v1/references/locations](/#operation/api__post__v1__references__locations) endpoint.',)
      - `name` string, required: Location name.
      - `administrative_level` string, required: Location administrative level.
      - `zip_codes` string[]: The location zip codes.
    - `address` string, required: Property address.
    - `zip_code` string, nullable, required: The location zip code.
    - `cadastral_reference` string, nullable, required: Cadastral reference of the estate.
    - `coordinates` object, nullable, required: Property coordinates.
      - `latitude` number, required: Latitude.
      - `longitude` number, required: Longitude.
    - `condition` 'used' | 'ruin' | 'very-good' | 'new' | 'other', required: Property condition, as returned by the [GET /api/v1/references/conditions](/#operation/api__get__v1__references__conditions) endpoint.
    - `contacts_info` object, required: Information about listing contacts.
      - `name` string, nullable, required: The owner name. Only for FSBO listings.
      - `email` string, email, nullable, required: The email contact.
      - `phone` string, nullable, required: The phone contact.
    - `total_area` integer, required: Total area.
    - `living_area` integer, required: Living area.
    - `plot_area` integer, required: Plot area.
    - `terrace_area` integer, required: Terrace area.
    - `bedrooms` integer, nullable, required: Number of bedrooms.
    - `rooms` integer, required: Number of rooms.
    - `bathrooms` integer, required: Number of bathrooms.
    - `features` object, required: Property features, as returned by the [GET /api/v1/references/features](/#operation/api__get__v1__references__features) endpoint.
      - `floor` 'no_floor' | 'ground' | 'middle' | 'top', nullable, required: Floor type.
      - `orientation` 'exterior' | 'interior', nullable, required: Property view orientation.
      - `view` 'water' | 'landscape' | 'city' | 'golf' | 'park', nullable, required: View from the property. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `views` field instead.</strong>
      - `views` string[], nullable, required: List of views from the property.
      - `direction` 'north' | 'south' | 'east' | 'west', nullable, required: Cardinal direction the property faces. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `directions` field instead.</strong>
      - `directions` string[], nullable, required: List of cardinal directions the property faces.
      - `characteristics` string[], nullable, required: Property characteristics.
    - `construction_year` integer, required: Construction year.
    - `operations` string[], required: Operation types for which listing property is available.
    - `is_bank_property` boolean, required: Whether the listing property is a bank property.
    - `is_auction_property` boolean, required: Whether the listing property is an auction property.
    - `is_new_development_property` boolean, required: Whether the listing property is a new development property.
    - `is_private_property` boolean, required: Whether the property is listed by a private individual, as opposed to an agent or a professional.
    - `sale_status` 'active' | 'reserved' | 'hold' | 'sold' | 'none', required: Current sale status of the listing.
    - `sale_currency` string, required: Sale price currency code.
    - `sale_price_base` integer, required: Current sale price, in Euros.
    - `sale_price` integer, required: Current sale price, in the currency of the listing (specified by the `sale_currency` field).
    - `sale_price_per_sqm` number, required: Current sale price per square meter, in the currency of the listing (specified by the `sale_currency` field).
    - `sale_price_per_sqm_base` number, required: Current sale price per square meter, in Euros.
    - `rent_status` 'active' | 'reserved' | 'hold' | 'rented' | 'none', required: Current rent status of the listing.
    - `rent_currency` string, required: Rent price currency code.
    - `rent_price_base` integer, required: Current rent price, in Euros.
    - `rent_price` integer, required: Current rent price, in the currency of the listing (specified by the `rent_currency` field).
    - `rent_price_per_sqm` number, required: Current rent price per square meter, in the currency of the listing (specified by the `rent_currency` field).
    - `rent_price_per_sqm_base` number, required: Current rent price per square meter, in Euros.
    - `rent_period` 'day' | 'week' | 'fortnight' | 'month' | 'year' | 'none', required: Rent period.
    - `agency_legal_id` string, required: Agency legal identifier specified on the source. Only for France and its overseas territories(DROM and COM).
    - `agency` string, required: The company that manages the listing.
    - `agent` string, required: The agent that manages the listing.
    - `source_name` string, required: The name of the source.
    - `description` string, required: Listing description.
    - `thumbnails` string[]: List of the thumbnail image URLs.
    - `pictures` string[]: List of the original picture image URLs.
    - `created_at` string, date-time, required: Date and time when the alert was created (UTC).
    - `created_at_with_photos` string, date-time, nullable, required: Date and time (UTC) when the alert was created and its photos were processed. Can be `null` if photo processing has not finished yet. If the listing has no photos but the system has finished the processing, this field will contain its date and time.
    - `updated_at` string, date-time, required: Date and time when the alert data was updated (UTC).
    - `energy_certificate` string, required: Energy certificate classification that attests to the energy efficiency of a listing. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `energy_rating` field instead.</strong>
    - `energy_rating` string, required: Energy rating that attests to the energy efficiency of a listing.
    - `heating_type` string, required: Type of heating.
    - `available_from` string, date, nullable, required: The date the listing property becomes available for occupancy. The start of the availability window.
    - `available_to` string, date, nullable, required: The date the listing property stops being available. The end of the availability window.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden

---

[API](https://skmtc.dev/casafari/apis/casafari-api.md) · [All operations](https://skmtc.dev/casafari/apis/casafari-api/llms.txt) · [OpenAPI document](https://skmtc.dev/casafari/apis/casafari-api/revisions/6743b99d4bf9?raw)