Tenants & Owners

Copy page

Owners API

Manage property owners — individuals, companies, or SCI/SC (Societe Civile Immobiliere). Owners are linked to buildings and apartments. Every place needs an owner before you can create leases.

Quick Example

Code
 
curl -X POST https://api.faireplace.com/api/owners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mr.",
    "first_name": "Jean",
    "last_name": "Dupont",
    "owner_category": "individual",
    "email": "[email protected]",
    "mobile_phone": "+33612345678",
    "street_name": "15 rue de Rivoli",
    "postal_code": "75001",
    "city": "Paris",
    "country": "France"
  }'

Common Workflows

Create an SCI owner

1. POST /api/owners — Set owner_category: "sc/sci", include legal_name and registration_number
2. POST /api/places — Create place with this owner's ID

Find which properties an owner has

1. GET /api/owners/places/{place_id}/owner — Get owner of a specific building
2. GET /api/owners/estates/{estate_id}/owner — Get owner of a specific unit

---

Overview

The Owners API provides comprehensive owner management with support for:

• Individual Owners: Personal property owners with contact information
• Corporate Owners: Companies and businesses that own properties
• SCI/SC Entities: Société Civile/Société Civile Immobilière (French investment structures)
• Address Management: Complete address information for owners
• Property Associations: Link owners to their places and estates
• Authentication Integration: Connection with Better Auth system

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 owner endpoints are prefixed with /api/owners

---

Core Owner Operations

List Owners

GET /api/owners

Retrieve all owners for the tenant.

Response:

Code
 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Mr.",
    "last_name": "Dupont",
    "first_name": "Jean",
    "owner_category": "individual",
    "legal_name": null,
    "registration_number": null,
    "country": "France",
    "address_complement": "Batiment A",
    "street_number": "123",
    "street_name": "Rue de la République",
    "locality": "Centre Ville",
    "postal_code": "75001",
    "city": "Paris",
    "postal_box": null,
    "mobile_phone": "+33612345678",
    "landline_phone": "+33123456789",
    "email": "[email protected]",
    "auth_user_id": "auth_user_123",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Create Owner

POST /api/owners

Create a new property owner.

Request Body:

Code
 
{
  "title": "Ms.",
  "last_name": "Martin",
  "first_name": "Marie",
  "owner_category": "individual",
  "country": "France",
  "street_number": "456",
  "street_name": "Avenue des Champs-Élysées",
  "postal_code": "75008",
  "city": "Paris",
  "mobile_phone": "+33698765432",
  "landline_phone": "+33187654321",
  "email": "[email protected]"
}

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

Get Owner

GET /api/owners/{id}

Retrieve a specific owner by ID.

Path Parameters:

• id (UUID): The owner ID

Response: 200 OK Returns the owner object.

Update Owner

PUT /api/owners/{id}

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

Path Parameters:

• id (UUID): The owner ID

Request Body:

Code
 
{
  "email": "[email protected]",
  "mobile_phone": "+33612345678",
  "address_complement": "Updated address complement"
}

Response: 200 OK Returns the updated owner object.

Delete Owner

DELETE /api/owners/{id}

Delete an owner (only possible if not associated with properties).

Path Parameters:

• id (UUID): The owner ID

Response: 204 No Content

---

Property Association Operations

Get Owner by Place

GET /api/owners/places/{id}/owner

Retrieve the owner of a specific place.

Path Parameters:

• id (UUID): The place ID

Response: 200 OK Returns the owner object associated with the place.

Example Response:

Code
 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Mme",
  "last_name": "Lefebvre",
  "first_name": "Claire",
  "owner_category": "individual",
  "country": "France",
  "street_name": "12 rue de Clichy",
  "postal_code": "75009",
  "city": "Paris",
  "mobile_phone": "+33612345679",
  "email": "[email protected]",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Get Owner by Estate

GET /api/owners/estates/{id}/owner

Retrieve the owner of a specific estate.

Path Parameters:

• id (UUID): The estate ID

Response: 200 OK Returns the owner object associated with the estate.

---

Data Types and Structures

Owner Categories

• individual - Individual person owner
• company - Corporate entity owner
• sc/sci - Société Civile/Société Civile Immobilière

Individual Owner Fields

Code
 
{
  "title": "Mr./Ms./Dr.",               // Required, max 10 chars
  "last_name": "string",               // Required, max 255 chars
  "first_name": "string",              // Optional, max 255 chars
  "owner_category": "individual",      // Required
  "legal_name": null,                  // Not used for individuals
  "registration_number": null,         // Not used for individuals
  "country": "string",                 // Required, max 50 chars
  "address_complement": "string",      // Optional, max 255 chars
  "street_number": "string",           // Optional, max 50 chars
  "street_name": "string",             // Required, max 255 chars
  "locality": "string",                // Optional, max 255 chars
  "postal_code": "string",             // Required, max 20 chars
  "city": "string",                    // Required, max 255 chars
  "postal_box": "string",              // Optional, max 20 chars
  "mobile_phone": "string",            // Required, max 20 chars
  "landline_phone": "string",          // Optional, max 20 chars
  "email": "[email protected]",        // Required, valid email
  "auth_user_id": "string"             // Optional
}

Company Owner Fields

Code
 
{
  "title": "CEO/Director",             // Required, max 10 chars
  "last_name": "Company Name",         // Required (can be company name)
  "first_name": "Contact Person",      // Optional
  "owner_category": "company",         // Required
  "legal_name": "Legal Company Name",  // Optional, max 255 chars
  "registration_number": "SIRET123",   // Optional, max 50 chars
  "country": "string",                 // Required
  "street_name": "Business Address",   // Required
  "postal_code": "string",             // Required
  "city": "string",                    // Required
  "mobile_phone": "string",            // Required
  "email": "[email protected]",      // Required
  "auth_user_id": "string"             // Optional
}

SCI/SC Owner Fields

Code
 
{
  "title": "Manager",                  // Required
  "last_name": "SCI Name",             // Required
  "first_name": "Manager Name",        // Optional
  "owner_category": "sc/sci",          // Required
  "legal_name": "Full SCI Legal Name", // Optional
  "registration_number": "SCI123456",  // Optional
  "country": "France",                 // Required
  "street_name": "SCI Address",        // Required
  "postal_code": "string",             // Required
  "city": "string",                    // Required
  "mobile_phone": "string",            // Required
  "email": "[email protected]",          // Required
  "auth_user_id": "string"             // Optional
}

---

Address Structure

Complete Address Fields

Code
 
{
  "country": "France",                    // Required - Country name
  "address_complement": "Batiment A",     // Optional - Building or additional info
  "street_number": "123",                 // Optional - Street number
  "street_name": "Rue de la République",  // Required - Street name
  "locality": "Centre Ville",            // Optional - District or locality
  "postal_code": "75001",                // Required - Postal/ZIP code
  "city": "Paris",                       // Required - City name
  "postal_box": "BP 12345"               // Optional - PO Box
}

Address Examples

Individual Owner Address:

Code
 
{
  "country": "France",
  "street_number": "45",
  "street_name": "Boulevard Saint-Germain",
  "postal_code": "75006",
  "city": "Paris"
}

Company Address:

Code
 
{
  "country": "France",
  "address_complement": "Tour Montparnasse, Étage 25",
  "street_number": "33",
  "street_name": "Avenue du Maine",
  "locality": "Montparnasse",
  "postal_code": "75015",
  "city": "Paris",
  "postal_box": "BP 2025"
}

---

Validation Rules

Required Fields by Category

• All Categories: title, last_name, owner_category, country, street_name, postal_code, city, mobile_phone, email
• Individual: No additional requirements
• Company: Should have legal_name and registration_number for legal compliance
• SC/SCI: Should have legal_name and registration_number for legal structure

Field Validation

• Title: 1-10 characters
• Last Name: 1-255 characters
• First Name: Max 255 characters
• Email: Valid email format with @ and domain
• Phone Numbers: Max 20 characters each
• Postal Code: Max 20 characters
• Registration Number: Max 50 characters for business entities

---

Error Responses

Validation Errors

400 Bad Request

Code
 
{
  "error": "ValidationError",
  "message": "Invalid owner data",
  "details": [
    {
      "field": "last_name",
      "message": "Last name is required and must be between 1 and 255 characters"
    },
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Category Validation Error

Code
 
{
  "error": "ValidationError",
  "message": "Invalid owner category",
  "details": [
    {
      "field": "owner_category",
      "message": "Category must be one of: individual, company, sc/sci"
    }
  ]
}

Not Found

404 Not Found

Code
 
{
  "error": "NotFound",
  "message": "Owner {id} not found"
}

Conflict

409 Conflict

Code
 
{
  "error": "Conflict", 
  "message": "Cannot delete owner with associated properties"
}

---

Common Use Cases

Creating an Individual Property Owner

1. Create owner with POST /api/owners
2. Set owner_category to "individual"
3. Provide personal information and contact details
4. Include complete address information
5. Associate with properties through estate/place management

Managing Corporate Property Owners

1. Create owner with owner_category set to "company"
2. Use company name in last_name field
3. Include contact person in first_name
4. Add legal company information in legal_name
5. Include business registration number

SCI/SC Investment Structures

1. Create owner with owner_category set to "sc/sci"
2. Provide SCI/SC legal name and registration
3. Include manager contact information
4. Set up proper legal documentation references

Finding Property Ownership

1. Use GET /api/owners/places/{id}/owner to find place owner
2. Use GET /api/owners/estates/{id}/owner to find estate owner
3. Cross-reference with property management records

Owner Contact Updates

1. Get current owner with GET /api/owners/{id}
2. Update contact information with PUT /api/owners/{id}
3. Verify changes are reflected in property records

---

Integration Notes

• Property Management: Owners are linked to places and estates
• Authentication: Integration with Better Auth through auth_user_id
• Legal Compliance: Different validation rules for entity types
• Contact Management: Integration with general contact system
• Document Management: Owner information used in lease documents
• Financial Systems: Owner details required for rent payments and tax reporting

---

Business Rules

• Email Uniqueness: Each owner should have a unique email address
• Property Association: Owners can be associated with multiple properties
• Deletion Constraints: Cannot delete owners with active property associations
• Legal Requirements: Company and SCI owners should have registration numbers
• Contact Verification: Mobile phone and email required for all communications
• Address Completeness: Street name, postal code, and city are mandatory
• Category Consistency: Owner type affects required legal documentation

---

French Legal Considerations

SCI (Société Civile Immobilière)

• Legal entity specifically for real estate investment
• Requires proper registration number
• Manager information must be accurate for legal compliance
• Tax implications require proper legal name documentation

Registration Numbers

• SIRET: For French companies (14 digits)
• SIREN: For business entities (9 digits)
• SCI Registration: Specific to civil real estate companies

Data Retention

• Owner personal data retained according to GDPR
• Business information retention follows commercial code requirements
• Property ownership records maintain legal audit trails