Introduction
Welcome to the Real Estate Open Protocol (REOP) API v1.1.0. This API standardizes global real estate development data, featuring a decoupled inventory architecture and AI-native search capabilities.
| Base URL | https://api.reop.io/v1 |
| Content-Type | application/json |
| Protocol | REOP v1.1.0 |
Authentication
Authentication is handled via Bearer Tokens. You must include the Authorization header in all requests.
Authorization: Bearer
Schema Reference
The REOP Protocol v1.1.0 defines a strict schema for all entities. Use this reference to find specific field names for your payloads.
1. The Golden Record
This is a complete example of a fully populated Project object. Click to expand and view all available nodes (Legal, Marketing, Specs, etc.).
2. How to Update Specific Fields
REOP supports Partial Updates via the PATCH method. You do not need to send the full object. You only need to send the path to the field you want to change.
| Goal | Endpoint | Payload |
|---|---|---|
| Update Hero Image | PATCH /projects/{id} |
{
"marketing": {
"heroImage": "https://new-url.com/img.jpg"
}
}
|
| Update Contact Info | PATCH /developers/{id} |
{
"contact": {
"email": "new_sales@example.com",
"whatsapp": "+97250000000"
}
}
|
| Update Unit Specs | PATCH .../unit-models/{id} |
{
"specs": {
"interiorAreaSqm": 105.5
}
}
|
Developers
Manage the root entities of the protocol.
| Method | Endpoint | Description |
|---|---|---|
| GET | /developers |
List all developers (Paginated). |
| POST | /developers |
Register a new Developer. Requires companyDetails. |
| GET | /developers/{id} |
Get full developer profile. |
| PATCH | /developers/{id} |
Update specific fields (logo, contact). |
| DEL | /developers/{id} |
Archive a developer. |
Projects
The core entity of REOP. Projects contain the full "Golden Record".
| Method | Endpoint | Description |
|---|---|---|
| GET | /projects |
List projects. Supports filtering ?city=Tel Aviv. |
| POST | /projects |
Create a Project. Accepts nested JSON. |
| GET | /projects/{id} |
Get the full Project JSON. |
| PUT | /projects/{id} |
Full Update (Replace). |
| PATCH | /projects/{id} |
Partial Update. |
Nested Hierarchy
Directly manipulate sub-nodes without sending the entire project payload.
| POST | /projects/{id}/unit-models |
Add a new Unit Model (e.g., "Type A"). |
| PATCH | /projects/{id}/unit-models/{modelId} |
Update specs for a specific model. |
| POST | /projects/{id}/buildings |
Add a new Building/Tower to a project. |
Inventory Management
Manage the availability of specific units. This is decoupled from the Project structure.
Update Availability
POST /inventory/status-update
Bulk update status for one, many, or all units in a scope.
Example A: Update Specific Units
{
"project_id": "prj_rothschild_collection",
"scope": "specific",
"unit_ids": ["u_1201", "u_1202"],
"status": "sold"
}
Example B: Release a Floor
{
"project_id": "prj_rothschild_collection",
"scope": "filter",
"filter": { "floor": 15 },
"status": "available"
}
Supported Statuses: available, reserved, sold, not_for_sale, booked.
Seed Search (AI Native)
The primary endpoint for AI Agents. Accepts a "Seed JSON" describing the buyer's intent.
POST /search/seed
Constraint: The seed object must contain at least 5 parameters.
{
"seed": {
"location": { "city": "Tel Aviv", "area": "Old North" },
"budget": { "max": 5000000, "currency": "ILS" },
"property_type": "apartment",
"rooms": { "min": 3 },
"purpose": "investment"
},
"preferences": ["quiet street", "near park", "bauhaus architecture"]
}
Smart Query
Flexible text-based filtering using Shortcuts and Operators. Ideal for search bars.
GET /search/query
Supported Syntax
- Shortcuts:
1M,500k - Units:
sqm,sqf - Operators:
>,<,:(Equals) - Amenities:
+pool(Must have),-gym(Exclude)
Examples
| Show all studio apartments with view to the sea | q=rooms:0 +view:sea |
| Studios, sea view, >40 sqm | q=rooms:0 +view:sea size>40sqm |
| Complex Location + Specs | q=location:"North Tel Aviv" rooms:0 +view:sea price<1M USD |
Dictionary
REOP enforces standardized naming for amenities, views, and interests. Use this dictionary to map your internal values to the protocol.
GET /meta/dictionary
Implementation Guide
Handling "Decoupled" Results:
Since REOP separates Catalog (Unit Models) from Inventory (Units), search results will have an item_type field.
| item_type: "model" | Generic layout (e.g., "Type A"). Price is usually startingPrice. Availability unknown. |
| item_type: "unit" | Specific physical unit. Price is exact. Availability is known. |
Example Response Object
{
"data": [
{
"id": "u_1201",
"item_type": "unit",
"title": "Unit 1201 - The Glass Tower",
"price": { "amount": 6350000, "currency": "ILS" },
"features": ["sea_view", "mamad"]
},
{
"id": "model_urban_2br",
"item_type": "model",
"title": "Type A - Boulevard View",
"startingPrice": { "amount": 6200000, "currency": "ILS" },
"note": "Contact developer for specific availability."
}
]
}