# Lease Types API

Define and configure lease type templates — the legal frameworks for rental agreements. Lease types determine duration, deposit limits, charge modes, rent revision rules, and document templates.

## Quick Example

```bash
# List available lease types
curl https://api.faireplace.com/api/lease-types \
  -H "Authorization: Bearer $API_KEY"

# Create a lease type
curl -X POST https://api.faireplace.com/api/lease-types \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_id": "<country_uuid>",
    "name": "Habitation vide 3 ans",
    "description": "Unfurnished residential lease, 3-year term, Loi du 6 juillet 1989",
    "is_furnished": false
  }'
```

## Common Lease Types

| Type | Duration | Deposit | Furnished | Use case |
|------|----------|---------|-----------|----------|
| Habitation vide | 3 years | 1 month | No | Standard unfurnished residential |
| Habitation meublee | 1 year | 2 months | Yes | Furnished residential |
| Mobilite etudiante | 1-10 months | 0 | Yes | Student/mobility lease |
| Commercial (3/6/9) | 9 years | Variable | N/A | Commercial use |
| Professionnel | 6 years | Variable | N/A | Professional use |

## Common Workflows

### Set up lease types for a new country
1. `GET /api/legislative-zones` — Get the country reference ([Rent Regulation & Rent Control API](/compliance/legislative-zones))
2. `POST /api/lease-types` — Create lease types linked to this country
3. `POST /api/lease-types/{id}/configurations` — Set duration, deposit, revision rules
4. `POST /api/lease-types/{id}/templates` — Add document templates

### Create a lease using a lease type
1. `GET /api/lease-types` — Browse available types
2. `GET /api/lease-types/{id}/configurations` — Check default parameters
3. `POST /api/leases` — Create lease with `lease_type_id` ([Leases API](/leases/leases))

---

## Authentication

Requires **LeasesRead**, **LeasesWrite**, or **LeasesDelete** permissions.

## Base URL

All endpoints: `/api/lease-types`

---

## Core Operations

### List Lease Types
**GET** `/api/lease-types`

**Query Parameters:**
- `country_id` (optional): Filter by country

**Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "country_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Habitation vide 3 ans",
    "description": "Unfurnished residential lease, 3-year term with annual IRL revision",
    "is_furnished": false,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
]
```

### Create Lease Type
**POST** `/api/lease-types`

**Request:**
```json
{
  "country_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Bail commercial 9 ans",
  "description": "Commercial lease, 3/6/9 year term",
  "is_furnished": false
}
```

### Get Lease Type
**GET** `/api/lease-types/{id}`

### Update Lease Type
**PUT** `/api/lease-types/{id}`

### Delete Lease Type
**DELETE** `/api/lease-types/{id}`

---

## Configurations

Configurations define the legal parameters for a lease type.

### List Configurations
**GET** `/api/lease-types/{lease_type_id}/configurations`

**Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "lease_type_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Standard configuration",
    "min_duration_months": 36,
    "max_duration_months": 36,
    "is_renewable": true,
    "requires_furnished": false,
    "deposit_months": 1,
    "rent_revision_frequency": "ANNUALLY",
    "rent_index_type": "IRL",
    "charge_mode": "PROVISION",
    "requires_inventory": true,
    "requires_professional_insurance": false,
    "requires_guarantor": true,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
]
```

### Create Configuration
**POST** `/api/lease-types/{lease_type_id}/configurations`

**Request:**
```json
{
  "name": "Standard configuration",
  "min_duration_months": 36,
  "max_duration_months": 36,
  "is_renewable": true,
  "requires_furnished": false,
  "deposit_months": 1,
  "rent_revision_frequency": "ANNUALLY",
  "rent_index_type": "IRL",
  "charge_mode": "PROVISION",
  "requires_inventory": true,
  "requires_professional_insurance": false,
  "requires_guarantor": true
}
```

### Get Configuration
**GET** `/api/lease-types/{lease_type_id}/configurations/{config_id}`

### Update Configuration
**PUT** `/api/lease-types/{lease_type_id}/configurations/{config_id}`

### Delete Configuration
**DELETE** `/api/lease-types/{lease_type_id}/configurations/{config_id}`

---

## Templates

Document templates for generating lease PDFs and related documents.

### List Templates
**GET** `/api/lease-types/{lease_type_id}/templates`

**Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "lease_type_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Standard unfurnished lease template",
    "description": "Default template for unfurnished residential leases",
    "template_type": "lease",
    "version": "1.0.0",
    "is_active": true,
    "is_default": false,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
]
```

### Template Types

| Type | Description |
|------|-------------|
| `lease` | Main lease agreement document |
| `amendment` | Lease amendment (avenant) |
| `termination` | Termination notice (resiliation) |
| `inventory` | Entry/exit inventory (etat des lieux) |

### Create Template
**POST** `/api/lease-types/{lease_type_id}/templates`

### List Templates by Type
**GET** `/api/lease-types/{lease_type_id}/templates/type/{type}`

### Get Active Template
**GET** `/api/lease-types/{lease_type_id}/templates/active/{type}`

### Get Default Template
**GET** `/api/lease-types/{lease_type_id}/templates/default/{type}`

### Get Specific Template
**GET** `/api/lease-types/{lease_type_id}/templates/{template_id}`

### Update Template
**PUT** `/api/lease-types/{lease_type_id}/templates/{template_id}`

### Delete Template
**DELETE** `/api/lease-types/{lease_type_id}/templates/{template_id}`

---

## Charge Configuration

Default charge setup for a lease type, applied automatically when creating new leases.

### Get Charge Configuration
**GET** `/api/lease-types/{lease_type_id}/charges/config`

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_type_id": "550e8400-e29b-41d4-a716-446655440001",
  "charge_mode": "PROVISION",
  "responsible_party": "TENANT",
  "default_charges": [
    {
      "name": "Chauffage collectif",
      "amount": 50.00,
      "is_mandatory": true,
      "calculation_method": "FIXED"
    }
  ],
  "distribution_rules": [
    {
      "charge_name": "Chauffage collectif",
      "distribution_method": "SURFACE",
      "parameters": {}
    }
  ]
}
```

### Create Charge Configuration
**POST** `/api/lease-types/{lease_type_id}/charges/config`

### Update Charge Configuration
**PUT** `/api/lease-types/{lease_type_id}/charges/config`

### Delete Charge Configuration
**DELETE** `/api/lease-types/{lease_type_id}/charges/config`

---

## Enums

### Rent Revision Index Types
| Value | Description |
|-------|-------------|
| `IRL` | Indice de Reference des Loyers — standard for residential |
| `ICC` | Indice du Cout de la Construction — used for commercial |
| `ILAT` | Indice des Loyers des Activites Tertiaires — for office leases |
| `ILC` | Indice des Loyers Commerciaux — used for commercial leases |
| `NONE` | No revision index |

### Charge Modes
| Value | Description |
|-------|-------------|
| `PROVISION` | Estimated charges with annual settlement (regularisation) |
| `FORFAIT` | Fixed charges, no settlement |

### Responsible Party
| Value | Description |
|-------|-------------|
| `TENANT` | Tenant pays |
| `LANDLORD` | Landlord pays |
| `NEGOTIABLE` | Negotiable between parties |

---

## Error Responses

**400 Bad Request**
```json
{
  "error": {
    "code": 400,
    "type": "VALIDATION_ERROR",
    "message": "Name is required"
  }
}
```

**404 Not Found**
```json
{
  "error": {
    "code": 404,
    "type": "NOT_FOUND",
    "message": "Lease type not found"
  }
}
```

---

## Related

- **[Leases API](/leases/leases)** — Create leases using these types
- **[Rent Regulation & Rent Control API](/compliance/legislative-zones)** — Country-level regulations
- **[Charges API](/leases/charges)** — Charge management for leases