Property Management

Copy page

Places API

Manage buildings, complexes, and property sites. Places are the top-level containers in the property hierarchy — every apartment, office, or commercial unit belongs to a place.

Quick Example

Code
 
curl -X POST https://api.faireplace.com/api/places \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Residence Les Jardins",
    "type_id": "<place_type_uuid>",
    "legislative_zone_id": "<zone_uuid>",
    "owner_id": "<owner_uuid>",
    "address_line1": "24 rue du Faubourg Saint-Antoine",
    "postal_code": "75012",
    "city": "Paris",
    "place_category": "Collective",
    "legal_regime": "Copropriete"
  }'

Common Workflows

Set up a new apartment building

1. POST /api/places — Create the building
2. POST /api/places/{id}/estates — Add each apartment (Estates API)
3. POST /api/places/{id}/estates/{id}/rooms — Define room layouts (Rooms API)
4. POST /api/places/{id}/services — Configure building services

Add rent control to a property

1. GET /api/legislative-zones — Find the matching zone (Legislative Zones API)
2. POST /api/places — Create place with legislative_zone_id
3. Rent control rules are automatically applied to leases in this place

---

Overview

Places represent physical buildings or property complexes and serve as containers for:

• Estates: Individual rental units within the place
• Services: Building-wide services and amenities
• Energy Diagnostics: Building-level energy assessments
• Ownership: Current and historical ownership tracking
• Legal Information: Legal regime and administrative details
• Location Data: Address, coordinates, and access information

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

All place endpoints are prefixed with /api/places

---

Core Place Operations

List Places

GET /api/places

Retrieve all places for the tenant.

Response:

Code
 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Résidence Les Jardins",
    "address_line1": "123 Avenue de la République",
    "address_line2": "Bâtiment A",
    "postal_code": "75011",
    "city": "Paris",
    "latitude": 48.8566,
    "longitude": 2.3522,
    "description": "Modern residential complex with garden views",
    "type_id": "550e8400-e29b-41d4-a716-446655440010",
    "legislative_zone_id": "550e8400-e29b-41d4-a716-446655440020",
    "digicode": "A1234B",
    "number_of_floor": 8,
    "owner_id": "550e8400-e29b-41d4-a716-446655440030",
    "previous_owner_id": null,
    "construction_date": "2010-09-15T00:00:00",
    "renovation_date": "2020-05-20T00:00:00",
    "place_category": "Collective",
    "legal_regime": "Copropriete",
    "created_at": "2024-01-15T10:30:00",
    "updated_at": "2024-01-15T10:30:00"
  }
]

Create Place

POST /api/places

Create a new place (building or complex).

Request Body:

Code
 
{
  "name": "Villa Moderne",
  "type_id": "550e8400-e29b-41d4-a716-446655440010",
  "legislative_zone_id": "550e8400-e29b-41d4-a716-446655440020",
  "owner_id": "550e8400-e29b-41d4-a716-446655440030",
  "address_line1": "456 Rue de la Paix",
  "address_line2": "Entrée B",
  "postal_code": "75002",
  "city": "Paris",
  "latitude": 48.8654,
  "longitude": 2.3347,
  "description": "Luxury villa with modern amenities",
  "digicode": "B5678C",
  "number_of_floor": 3,
  "place_category": "Individual",
  "legal_regime": "MonoPropriete",
  "construction_date": "2015-03-10T00:00:00",
  "renovation_date": "2022-08-15T00:00:00"
}

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

Get Place

GET /api/places/{id}

Retrieve a specific place by ID.

Path Parameters:

• id (UUID): The place ID

Response: 200 OK Returns the place object.

Update Place

PUT /api/places/{id}

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

Path Parameters:

• id (UUID): The place ID

Request Body:

Code
 
{
  "name": "Résidence Les Jardins - Rénovée",
  "description": "Fully renovated residential complex with garden views",
  "renovation_date": "2024-01-15T00:00:00",
  "digicode": "A9999B"
}

Response: 200 OK Returns the updated place object.

Delete Place

DELETE /api/places/{id}

Delete a place (only possible if no estates are associated).

Path Parameters:

• id (UUID): The place ID

Response: 204 No Content

---

Nested Resources

Estates Management

See Estates API for detailed estate operations within places.

Places can contain multiple estates accessed through:

• GET /api/places/{id}/estates
• POST /api/places/{id}/estates
• And other estate-specific endpoints

Services Management

List Place Services

GET /api/places/{id}/services

Retrieve all services associated with a place.

Path Parameters:

• id (UUID): The place ID

Response: 200 OK

Code
 
[
  {
    "id": "service-550e8400-e29b-41d4-a716-446655440000",
    "place_id": "550e8400-e29b-41d4-a716-446655440000",
    "service_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Building Maintenance",
    "calculation_method": "PerSquareMeter",
    "space_type": "CommonAreas",
    "created_at": "2024-01-15T10:30:00Z"
  }
]

Add Service to Place

POST /api/places/{id}/services

Add a service to a place.

Path Parameters:

• id (UUID): The place ID

Request Body:

Code
 
{
  "service_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Elevator Maintenance"
}

Response: 201 Created Returns the created service association.

Remove Service from Place

DELETE /api/places/{id}/services/{service_id}

Remove a service from a place.

Path Parameters:

• id (UUID): The place ID
• service_id (UUID): The service ID

Response: 204 No Content

Energy Diagnostics

See Energy Diagnosis API for energy assessments.

Energy diagnostics for places accessed through:

• GET /api/places/{id}/energy-diagnoses

---

Data Types and Structures

Place Object

Code
 
{
  "id": "UUID",                        // Generated place ID
  "name": "string",                    // Place name/title
  "address_line1": "string",           // Primary address line
  "address_line2": "string",           // Secondary address line (optional)
  "postal_code": "string",             // Postal/ZIP code
  "city": "string",                    // City name
  "latitude": 48.8566,                // GPS latitude (optional)
  "longitude": 2.3522,                // GPS longitude (optional)
  "description": "string",             // Place description (optional)
  "type_id": "UUID",                   // Reference to place type
  "legislative_zone_id": "UUID",       // Reference to legislative zone
  "digicode": "string",                // Building access code (optional)
  "number_of_floor": 8,                // Number of floors (optional)
  "owner_id": "UUID",                  // Current owner ID
  "previous_owner_id": "UUID",         // Previous owner ID (optional)
  "construction_date": "ISO 8601",     // Construction date (optional)
  "renovation_date": "ISO 8601",       // Last renovation date (optional)
  "place_category": "PlaceCategory",   // Individual or Collective
  "legal_regime": "PlaceLegalRegime",  // Legal ownership structure
  "created_at": "ISO 8601",            // Creation timestamp
  "updated_at": "ISO 8601"             // Last update timestamp
}

Create Place Request

Code
 
{
  "name": "string",                    // Required
  "type_id": "UUID (as string)",       // Required
  "legislative_zone_id": "UUID (as string)", // Required
  "owner_id": "UUID (as string)",      // Required
  "address_line1": "string",           // Required
  "address_line2": "string",           // Optional
  "postal_code": "string",             // Required
  "city": "string",                    // Required
  "latitude": 48.8566,                // Optional
  "longitude": 2.3522,                // Optional
  "description": "string",             // Optional
  "digicode": "string",                // Optional
  "number_of_floor": 8,                // Optional
  "place_category": "PlaceCategory",   // Required
  "legal_regime": "PlaceLegalRegime",  // Required
  "construction_date": "ISO 8601",     // Optional
  "renovation_date": "ISO 8601"        // Optional
}

Update Place Request

All fields are optional and will only update provided values:

Code
 
{
  "name": "string",                    // Optional
  "address_line1": "string",           // Optional
  "address_line2": "string",           // Optional
  "postal_code": "string",             // Optional
  "city": "string",                    // Optional
  "latitude": 48.8566,                // Optional
  "longitude": 2.3522,                // Optional
  "description": "string",             // Optional
  "type_id": "UUID (as string)",       // Optional
  "legislative_zone_id": "UUID (as string)", // Optional
  "digicode": "string",                // Optional
  "number_of_floor": 8,                // Optional
  "place_category": "PlaceCategory",   // Optional
  "legal_regime": "PlaceLegalRegime",  // Optional
  "renovation_date": "ISO 8601"        // Optional
}

---

Enums and Categories

PlaceCategory

• Individual - Single-family property or individual building
• Collective - Multi-unit building or apartment complex

PlaceLegalRegime

• MonoPropriete - Single ownership (one owner for entire building)
• Copropriete - Co-ownership/Condominium (multiple owners in building)

---

Location and Address

Address Structure

Places require complete address information:

• address_line1: Primary street address (required)
• address_line2: Additional address details (optional)
• postal_code: Postal or ZIP code (required)
• city: City or municipality name (required)

GPS Coordinates

Optional latitude/longitude coordinates for mapping:

• latitude: Decimal degrees (-90.0 to 90.0)
• longitude: Decimal degrees (-180.0 to 180.0)

Building Access

• digicode: Entry code or access information
• number_of_floor: Total floors in building

---

Error Responses

Validation Errors

400 Bad Request

Code
 
{
  "error": "ValidationError",
  "message": "Invalid place data",
  "details": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "owner_id",
      "message": "Invalid owner ID format"
    }
  ]
}

Not Found

404 Not Found

Code
 
{
  "error": "NotFound",
  "message": "Place not found"
}

Dependency Constraint

409 Conflict

Code
 
{
  "error": "Conflict",
  "message": "Cannot delete place with associated estates"
}

---

Common Use Cases

Creating a New Apartment Building

1. Create place with POST /api/places
2. Set place_category to "Collective" and legal_regime to "Copropriete"
3. Include building access information (digicode, number of floors)
4. Add individual apartments as estates
5. Configure building-wide services

Managing Single-Family Properties

1. Create place with place_category set to "Individual"
2. Set legal_regime to "MonoPropriete"
3. Create single estate representing the entire property
4. Associate with individual owner

Building Service Management

1. Add services like maintenance, security, cleaning
2. Configure service calculation methods
3. Track service costs across all estates in the building

Ownership Transfer

1. Update previous_owner_id with current owner_id
2. Set new owner_id
3. Update associated estates if needed
4. Track ownership history through timestamps

Renovation Tracking

1. Update renovation_date when work is completed
2. Use description to describe renovation scope
3. Update building access codes if changed during renovation

---

Business Rules

• Required Relationships: Places must have valid type, legislative zone, and owner
• Address Validation: Complete address information is mandatory
• Ownership Consistency: All estates in a place should reflect place ownership
• Legal Regime: Must match the actual legal structure of the property
• Deletion Constraints: Cannot delete places with associated estates or services
• Construction Date: Cannot be in the future
• Coordinate Validation: GPS coordinates must be within valid ranges

---

Integration Notes

• Place Types: Reference to the Types API for place categorization
• Legislative Zones: Integration with Legislative Zones API
• Owners: Reference to Owners API for ownership management
• Estates: Places contain multiple estates through nested routes
• Services: Building-level services affect all estates
• Energy Diagnostics: Building-level assessments complement estate-level diagnostics
• Geographic Information: GPS coordinates enable mapping and location services

---

French Real Estate Context

Legal Regimes

• MonoPropriété: Single ownership, common for individual houses
• Copropriété: Condominium system governed by French law
• Legal regime affects maintenance responsibilities and decision-making

Building Categories

• Individual: Single-family homes, individual buildings
• Collective: Apartment buildings, mixed-use complexes
• Category affects regulatory requirements and management structure

Legislative Zones

Places must be associated with appropriate legislative zones for:

• Rent control regulations
• Urban planning compliance
• Tax calculations
• Legal requirement adherence