---
title: "Search properties by description"
method: POST
path: "/v1/property-sourcing/searches/describe"
tags: ["platform---property-sourcing"]
---

# Search properties by description

`POST /v1/property-sourcing/searches/describe`

## Request

- Base URL: `https://platform.casafari.com`
- URL: `https://platform.casafari.com/v1/property-sourcing/searches/describe`
- Auth: HTTP bearer

Plain-language search: say what you look for as `tags` (up to 20 phrases) or one `description` (split into phrases at commas, semicolons and "and"), in the places named by `location_ids`, optionally within a price or price-per-m² range. Each result lists the phrases it matched in `matched_tags`. Structured filters (types, bedrooms, features) belong to `POST /v1/property-sourcing/searches`. 100 tokens per page.

## Request body

- PropertySourcingDescribeRequest
  - `location_ids` integer[], required: 1 to 100 location ids, from GET /v1/locations/search?query=<place>.
  - `country` string: ISO 3166-1 alpha-2 code, e.g. "ES".
  - `operation` 'sale' | 'rent': For sale or for rent.
  - `tags` string[]: Up to 20 phrases, e.g. ["close to the beach", "sea views"]. Send tags or description, not both.
  - `description` string: What you look for in plain words, split into phrases at commas, semicolons and "and" (at most 20).
  - `price` PlatformRange: A range; either end may be left out.
    - `min` integer: Lowest value, inclusive.
    - `max` integer: Highest value, inclusive.
  - `price_per_sqm` PlatformRange: A range; either end may be left out.
    - `min` integer: Lowest value, inclusive.
    - `max` integer: Highest value, inclusive.
  - `page_size` integer: Results per page: up to 100 (25 on Free).

## Response `200`

One page of properties, each with the phrases it matched.

- PropertySourcingSearchPage
  - `results` PropertySourcingResult[]
    - `id` string: Opaque property id, `prop_...`.
    - `type` string, nullable: Property type.
    - `operation` 'sale' | 'rent'
    - `price` PlatformPrice
      - `amount` number, nullable: Asking price; null when the price is on request.
      - `currency` string, nullable: ISO 4217 currency code.
      - `per_sqm` number, nullable: Asking price per m².
    - `bedrooms` number, nullable
    - `living_area_sqm` number, nullable
    - `location` PlatformLocation
      - `id` integer, nullable: Location id.
      - `name` string, nullable: Location name.
      - `coordinates` object, nullable: Latitude and longitude.
        - `lat` number
        - `lon` number
    - `first_seen` string, nullable: When the property came on the market for this operation.
    - `listings_count` integer, nullable: How many listings advertise it; known on a property read with expand=listings, null in search results.
    - `matched_tags` string[], nullable: The phrases of a plain-language search this property matched; null for structured searches.
  - `total` integer, nullable: How many properties match, when known.
  - `next` string, nullable: URL of the next page (valid one hour), or null.

## Other responses

- `400`: Invalid request: the problem names each field to fix (`invalid_request`).
- `401`: Missing or unknown API key or token.
- `402`: No tokens left to fund the call (`payment_required`).
- `403`: The account is not entitled to this product or country (`not_entitled`).
- `429`: A request limit of the plan was reached (`request_limit_reached`).

---

[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)