Copy page

Property Management

Estates API

Manage individual rental units: apartments, studios, houses, or commercial spaces. Estates are the units you create leases for.

Quick Example

Code
curl -X POST https://api.faireplace.com/api/places/<place_uuid>/estates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "T2 - Apt 301",
    "estate_type_id": "<estate_type_uuid>",
    "area": 45.0,
    "fiscal_identifier": "75012-B-0301",
    "number_of_room": 2,
    "floor": 3,
    "address": "24 rue du Faubourg Saint-Antoine, Apt 301, 75012 Paris"
  }'

Common Workflows

List all units in a building

1. GET /api/places/{place_id}/estates: Returns all apartments in the building

Prepare a unit for leasing

1. POST /api/places/{id}/estates: Create the estate
2. POST /api/places/{id}/estates/{id}/rooms: Add rooms (Rooms API)
3. POST /api/leases: Create a lease for this estate (Leases API)

Track renovation

1. PUT /api/places/{id}/estates/{id}: Update renovation_date and other_detail
2. Energy diagnosis may need updating after renovation (Energy Diagnosis API)

Retire a unit (leases all terminated)

1. PUT /api/estates/{id}/archive: Archive the vacant unit (frees a quota slot; deletion would be blocked by lease history)
2. GET /api/estates/archived: Review archived units
3. PUT /api/estates/{id}/unarchive: Bring it back later (subject to quota)

---

Overview

Estates are individual property units that belong to places (buildings or complexes). Each estate contains:

• Physical Attributes: Area, rooms, orientation, floor
• Financial Information: Taxes, acquisition price, property values
• Legal Details: Lot numbers, fiscal identifiers
• Ownership: Current and previous owner tracking
• Room Management: Nested room structure for detailed space management
• Energy Diagnostics: Energy performance assessments

Authentication

All endpoints require authentication with the following permissions:

• PropertiesRead: For GET operations
• PropertiesWrite: For POST and PUT operations
• PropertiesDelete: For DELETE operations

Base URL

Estate endpoints are nested under places: /api/places/{place_id}/estates

---

Core Estate Operations

List Estates

GET /api/places/{place_id}/estates

Retrieve all estates belonging to a specific place.

Path Parameters:

• place_id (UUID): The place ID

Response:

Code
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "T3 - Apt 401",
    "place_id": "550e8400-e29b-41d4-a716-446655440010",
    "estate_type_id": "550e8400-e29b-41d4-a716-446655440020",
    "area": 75.5,
    "number_of_room": 3,
    "orientation": "South",
    "building": "Building A",
    "floor": 4,
    "owner_id": "550e8400-e29b-41d4-a716-446655440030",
    "previous_owner_id": null,
    "lot_number": "LOT-A-401",
    "fiscal_identifier": "13001-B-0123",
    "housing_tax": 850.00,
    "property_tax": 1200.00,
    "acquisition_price": 180000.00,
    "rent_amount": 1200.00,
    "rental_status": "RENTED",
    "construction_date": "2010-06-15T00:00:00",
    "renovation_date": "2018-03-20T00:00:00",
    "address": "123 Rue de la Paix, Apt 401",
    "other_detail": "Corner unit with balcony",
    "created_at": "2024-01-15T10:30:00",
    "updated_at": "2024-01-15T10:30:00"
  }
]

Create Estate

POST /api/places/{place_id}/estates

Create a new estate within a place.

Path Parameters:

• place_id (UUID): The place ID

Request Body:

Code
{
  "name": "T2 - Apt 203",
  "estate_type_id": "550e8400-e29b-41d4-a716-446655440020",
  "area": 62.0,
  "fiscal_identifier": "13001-B-0124",
  "number_of_room": 2,
  "orientation": "North-West",
  "building": "Building B",
  "floor": 2,
  "lot_number": "LOT-B-203",
  "housing_tax": 650.00,
  "property_tax": 900.00,
  "acquisition_price": 145000.00,
  "construction_date": "2010-06-15T00:00:00",
  "renovation_date": "2020-01-15T00:00:00",
  "address": "123 Rue de la Paix, Apt 203",
  "other_detail": "Recently renovated with modern fixtures"
}

Response: 201 Created Returns the created estate object with generated ID and timestamps.

Get Estate

GET /api/places/{place_id}/estates/{estate_id}

Retrieve a specific estate by ID within a place.

Path Parameters:

• place_id (UUID): The place ID
• estate_id (UUID): The estate ID

Response: 200 OK Returns the estate object.

Update Estate

PUT /api/places/{place_id}/estates/{estate_id}

Update an existing estate. All fields are optional in update requests.

Path Parameters:

• place_id (UUID): The place ID
• estate_id (UUID): The estate ID

Request Body:

Code
{
  "area": 65.0,
  "number_of_room": 3,
  "renovation_date": "2024-02-15T00:00:00",
  "other_detail": "Updated with new kitchen and bathroom"
}

Response: 200 OK Returns the updated estate object.

Delete Estate

DELETE /api/places/{place_id}/estates/{estate_id}

Delete an estate from a place.

Path Parameters:

• place_id (UUID): The place ID
• estate_id (UUID): The estate ID

Response: 204 No Content

Deletion is only for genuine mistakes. An estate that is (or ever was) referenced by a lease cannot be deleted: the request returns 409 Conflict, even when every lease is TERMINATED, because lease history is protected. To take a unit out of your active portfolio without losing its history, archive it instead (see below).

---

Archiving

Archiving takes an estate out of your active portfolio without deleting it. An archived estate:

• keeps all its history (leases, documents, timestamps): nothing is removed;
• disappears from the default listings (GET /api/estates and GET /api/places/{place_id}/estates only return non-archived estates);
• no longer counts toward your estate quota, so archiving a unit frees a slot on your plan.

This is the intended way to retire a unit whose leases are all terminated: the case where deletion is blocked by the 409 Conflict above.

Archiving is an orthogonal flag (archived_at), not a status change: rental_status is untouched.

Archive an Estate

PUT /api/estates/{id}/archive (flat route) PUT /api/places/{place_id}/estates/{estate_id}/archive (nested route)

Archive a vacant estate. Only estates with rental_status of VACANT (no active or in-notice lease) can be archived.

Response: 200 OK: returns the estate with archived_at set.

Code
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "T3 - Apt 401",
  "rental_status": "VACANT",
  "archived_at": "2026-07-16T17:45:13.445743",
  "...": "…other estate fields…"
}

Archiving is idempotent: archiving an already-archived estate returns 200 OK with the original archived_at unchanged.

Errors:

• 422 Unprocessable Entity: the estate is RENTED or NOTICE (only vacant estates can be archived).

Unarchive an Estate

PUT /api/estates/{id}/unarchive (flat route)

Bring an archived estate back into the active portfolio. Because the estate re-enters the estate quota, this endpoint is quota-gated exactly like creation.

Response: 200 OK: returns the estate with archived_at set back to null.

Errors:

• 403 Forbidden: PLAN_LIMIT_REACHED: unarchiving would exceed your plan's active-estate limit. Free a slot (archive another unit or upgrade) and retry.

Code
{
  "error": {
    "code": "PLAN_LIMIT_REACHED",
    "message": "Plan limit reached: Limite de estate atteinte (3/3). Passez à un plan supérieur.",
    "status": 403
  }
}

List Archived Estates

GET /api/estates/archived

Returns all archived estates for the tenant, most recently archived first.

Response: 200 OK: an array of estate objects (each with archived_at set).

---

Nested Resources

Rooms Management

See Rooms API for detailed room operations within estates.

Estates can contain multiple rooms accessed through:

• GET /api/places/{place_id}/estates/{estate_id}/rooms
• POST /api/places/{place_id}/estates/{estate_id}/rooms
• And other room-specific endpoints

Energy Diagnostics

See Energy Diagnosis API for energy performance assessments.

Energy diagnostics for estates accessed through:

• GET /api/places/{place_id}/estates/{estate_id}/energy-diagnoses

---

Data Types and Structures

Estate Object

Field	Type	Description
id	UUID	Generated estate ID
name	string	Property name (e.g. "T3 - Apt 401")
place_id	UUID	Parent place ID
estate_type_id	UUID	Reference to estate type
area	number	Area in square meters
number_of_room	integer	Number of rooms
orientation	string	Compass orientation
building	string	Building identifier
floor	integer	Floor number
owner_id	UUID	Current owner ID
previous_owner_id	UUID	Previous owner ID
lot_number	string	Legal lot number
fiscal_identifier	string	Tax/fiscal identifier
housing_tax	number	Annual housing tax
property_tax	number	Annual property tax
acquisition_price	number	Purchase price
rent_amount	number	Reference rent amount (euros). Auto-synced with active leases.
rental_status	enum	VACANT, RENTED, NOTICE. Auto-synced with lease status.
construction_date	datetime	Construction date
renovation_date	datetime	Last renovation date
address	string	Full address
other_detail	string	Additional details
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp
archived_at	datetime | null	Archive timestamp. null = active (counts toward quota); set = archived (out of quota, hidden from default listings). See Archiving.

Required Fields for Creation

name (1-255 chars), estate_type_id, area, fiscal_identifier (1-50 chars)

Update Estate Request

All fields are optional. Absent fields are preserved, null removes the value. The place_id field can be changed via the flat route PUT /estates/{id} to move a property to another place.

---

Common Orientations

Typical values for the orientation field:

• North
• South
• East
• West
• North-East
• North-West
• South-East
• South-West

---

Error Responses

Validation Errors

400 Bad Request

Code
{
  "error": "ValidationError",
  "message": "Invalid input data",
  "details": [
    {
      "field": "area",
      "message": "Area must be greater than 0"
    },
    {
      "field": "estate_type_id",
      "message": "Invalid estate type ID format"
    }
  ]
}

Not Found

404 Not Found

Code
{
  "error": "NotFound",
  "message": "Estate with id {estate_id} not found under place {place_id}"
}

Place Validation Error

When estate doesn't belong to the specified place:

Code
{
  "error": "NotFound", 
  "message": "Estate with id {estate_id} not found under place {place_id}"
}

---

Common Use Cases

Creating a New Apartment

1. Identify the parent place (building)
2. Choose appropriate estate type (apartment)
3. Create estate with POST /api/places/{place_id}/estates
4. Add rooms using the rooms API
5. Attach energy diagnostics if required

Property Tax Management

1. Get estate with GET /api/places/{place_id}/estates/{estate_id}
2. Update tax values with PUT /api/places/{place_id}/estates/{estate_id}
3. Track historical changes through timestamps

Renovation Tracking

1. Update renovation_date when work is completed
2. Use other_detail to describe renovation scope
3. Update area if renovations change square footage

Ownership Transfer

1. Update previous_owner_id with current owner_id
2. Set new owner_id
3. Update acquisition_price if applicable

Multi-Building Management

1. Use building field to identify specific buildings
2. Use floor for vertical organization
3. Use lot_number for legal subdivision tracking

---

Business Rules

• Area Validation: Area must be greater than 0
• Place Association: Estates must belong to exactly one place
• Owner Tracking: Previous owner is automatically set during ownership transfers
• Type Reference: Estate type must exist in the types system
• Nested Updates: Updating estate also updates the updated_at timestamp
• Deletion Constraints: An estate referenced by any lease (of any status, including TERMINATED) cannot be deleted (409 Conflict): archive it instead
• Archiving: Only VACANT estates can be archived; archived estates leave the estate quota and the default listings but keep all history
• Quota: The plan estate quota counts only active (non-archived) estates; unarchiving is blocked (403 PLAN_LIMIT_REACHED) when it would exceed the limit

---

Integration Notes

• Estate Types: Reference to the Types API for estate categorization
• Owners: Integration with owner management system
• Rooms: Estates can contain multiple rooms with detailed layouts
• Leases: Estates are the primary unit for lease agreements
• Energy Diagnostics: Required for certain property types and regulations
• Financial Calculations: Tax values used for lease calculations and reporting