# 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

```bash
curl -X POST https://api.faireplace.com/api/owners \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mr.",
    "first_name": "Jean",
    "last_name": "Dupont",
    "owner_category": "individual",
    "email": "jean.dupont@example.com",
    "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:**
```json
[
  {
    "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": "jean.dupont@example.com",
    "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:**
```json
{
  "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": "marie.martin@example.com"
}
```

**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:**
```json
{
  "email": "marie.martin.updated@example.com",
  "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:**
```json
{
  "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": "claire.lefebvre@example.com",
  "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
```json
{
  "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@example.com",        // Required, valid email
  "auth_user_id": "string"             // Optional
}
```

### Company Owner Fields
```json
{
  "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": "contact@company.com",      // Required
  "auth_user_id": "string"             // Optional
}
```

### SCI/SC Owner Fields
```json
{
  "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": "manager@sci.com",          // Required
  "auth_user_id": "string"             // Optional
}
```

---

## Address Structure

### Complete Address Fields
```json
{
  "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:**
```json
{
  "country": "France",
  "street_number": "45",
  "street_name": "Boulevard Saint-Germain",
  "postal_code": "75006",
  "city": "Paris"
}
```

**Company Address:**
```json
{
  "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**
```json
{
  "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
```json
{
  "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**
```json
{
  "error": "NotFound",
  "message": "Owner {id} not found"
}
```

### Conflict
**409 Conflict**
```json
{
  "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