Property Management

Copy page

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 $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "estate_type_id": "<estate_type_uuid>",
    "area": 45.0,
    "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)

---

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",
    "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,
    "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
 
{
  "estate_type_id": "550e8400-e29b-41d4-a716-446655440020",
  "area": 62.0,
  "number_of_room": 2,
  "orientation": "North-West",
  "building": "Building B",
  "floor": 2,
  "lot_number": "LOT-B-203",
  "fiscal_identifier": "13001-B-0124",
  "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

---

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

Code
 
{
  "id": "UUID",                    // Generated estate ID
  "place_id": "UUID",              // Parent place ID
  "estate_type_id": "UUID",        // Reference to estate type
  "area": 75.5,                    // Area in square meters
  "number_of_room": 3,             // Number of rooms (optional)
  "orientation": "South",          // Compass orientation (optional)
  "building": "Building A",        // Building identifier (optional)
  "floor": 4,                      // Floor number (optional)
  "owner_id": "UUID",              // Current owner ID (optional)
  "previous_owner_id": "UUID",     // Previous owner ID (optional)
  "lot_number": "LOT-A-401",       // Legal lot number (optional)
  "fiscal_identifier": "13001-B-0123", // Tax/fiscal ID (optional)
  "housing_tax": 850.00,           // Annual housing tax (optional)
  "property_tax": 1200.00,         // Annual property tax (optional)
  "acquisition_price": 180000.00,  // Purchase price (optional)
  "construction_date": "ISO 8601", // Construction date (optional)
  "renovation_date": "ISO 8601",   // Last renovation date (optional)
  "address": "string",             // Full address (optional)
  "other_detail": "string",        // Additional details (optional)
  "created_at": "ISO 8601",        // Creation timestamp
  "updated_at": "ISO 8601"         // Last update timestamp
}

Create Estate Request

Code
 
{
  "estate_type_id": "UUID (as string)", // Required
  "area": 75.5,                         // Required
  "number_of_room": 3,                  // Optional
  "orientation": "string",              // Optional
  "building": "string",                 // Optional
  "floor": 4,                          // Optional
  "lot_number": "string",              // Optional
  "fiscal_identifier": "string",       // Optional
  "housing_tax": "BigDecimal",         // Optional
  "property_tax": "BigDecimal",        // Optional
  "acquisition_price": "BigDecimal",   // Optional
  "construction_date": "ISO 8601",     // Optional
  "renovation_date": "ISO 8601",       // Optional
  "address": "string",                 // Optional
  "other_detail": "string"             // Optional
}

Update Estate Request

All fields are optional and will only update provided values:

Code
 
{
  "estate_type_id": "UUID (as string)", // Optional
  "area": 75.5,                         // Optional
  "number_of_room": 3,                  // Optional
  "orientation": "string",              // Optional
  "building": "string",                 // Optional
  "floor": 4,                          // Optional
  "lot_number": "string",              // Optional
  "fiscal_identifier": "string",       // Optional
  "housing_tax": "BigDecimal",         // Optional
  "property_tax": "BigDecimal",        // Optional
  "acquisition_price": "BigDecimal",   // Optional
  "construction_date": "ISO 8601",     // Optional
  "renovation_date": "ISO 8601",       // Optional
  "address": "string",                 // Optional
  "other_detail": "string"             // Optional
}

---

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: Cannot delete estates with active leases or rooms

---

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