Copy page

Lease Management

Lease Amendments (Avenants)

Lease amendments allow you to formally modify the terms of an active lease. Every modification to a lease — rent changes, duration extensions, tenant replacements, early terminations — must go through an amendment to maintain a complete legal audit trail.

Legal Framework

The amendment system is built to comply with French real estate law:

Law	Article	Requirement
Loi 89-462	Art. 12	Owner approval required for tenant/guarantor modifications
Loi 89-462	Art. 15	Minimum 90-day notice for early termination
Loi 89-462	Art. 17-1	Rent revision rules (index-based)
Loi 89-462	Art. 17-2	Rent cap in zone tendue (reference rent)
ALUR	Decret 2015-587	Reference rent enforcement
Code Civil	Art. 1367	Electronic signature validity

Amendment Types

Type	Description	Sub-resource
RENT_MODIFICATION	Change the monthly rent amount	Rent Detail (1:1)
DURATION_MODIFICATION	Extend or reduce the lease duration	Duration Detail (1:1)
RENEWAL	Renew the lease for a new term	Duration Detail (1:1)
TENANT_MODIFICATION	Replace or add a tenant	Lease Lessee API
GUARANTOR_MODIFICATION	Replace or add a guarantor	Lease Lessee API
CHARGE_MODIFICATION	Modify service charges	Charge module
CONDITION_MODIFICATION	Update lease special conditions	—
EARLY_TERMINATION	Terminate the lease before end date	—
OTHER	Generic amendment	—

Status Lifecycle

Code
DRAFT ──> PENDING_SIGNATURE ──> SIGNED ──> ACTIVE (terminal)
  │              │
  ├──> REJECTED  ├──> REJECTED
  │              │
  └──> CANCELLED └──> CANCELLED

                                          EXPIRED (terminal, set by system)

Allowed transitions

From	To	Trigger
DRAFT	PENDING_SIGNATURE	Initiate signature
DRAFT	REJECTED	Reject amendment
DRAFT	CANCELLED	Cancel amendment
PENDING_SIGNATURE	SIGNED	All parties signed
PENDING_SIGNATURE	REJECTED	Reject during signature
PENDING_SIGNATURE	CANCELLED	Cancel during signature
SIGNED	ACTIVE	Activate (applies changes to lease)

Activation requirements

When transitioning from SIGNED to ACTIVE, the system:

1. Checks all mandatory validations are APPROVED (blocks if PENDING or REJECTED)
2. Verifies the lease is in ACTIVE status
3. Applies the amendment changes to the lease (type-specific logic)
4. Validates business rules (e.g., rent cap in zone tendue)
5. Transitions the amendment status
6. Fires notifications to relevant parties

Conflict detection

Only one amendment of the same type can be in a non-terminal status (DRAFT, PENDING_SIGNATURE, or SIGNED) per lease at any time. Creating a second amendment of the same type while one is in progress returns a 400 error.

---

Core CRUD Operations

Create an amendment

Code
POST /leases/{lease_id}/amendments

Request body:

Required fields: amendment_type, effective_date, created_by. All other fields are optional.

Code
{
  "amendment_type": "RENT_MODIFICATION",
  "effective_date": "2025-07-01",
  "description": "Annual rent revision based on IRL Q1 2025",
  "legal_reference": "Art. 17-1 Loi 89-462",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

Auto-created validations: For TENANT_MODIFICATION, GUARANTOR_MODIFICATION, and EARLY_TERMINATION, a mandatory OWNER validation is automatically created (Art. 12 & 15 Loi 89-462).

List amendments

Code
GET /leases/{lease_id}/amendments

Returns all amendments for the lease, ordered by creation date.

Get a specific amendment

Code
GET /leases/{lease_id}/amendments/{amendment_id}

Update an amendment

Code
PUT /leases/{lease_id}/amendments/{amendment_id}

Only allowed while the amendment is in DRAFT status.

Delete an amendment

Code
DELETE /leases/{lease_id}/amendments/{amendment_id}

Change status

Code
PUT /leases/{lease_id}/amendments/{amendment_id}/status

Code
{
  "status": "ACTIVE",
  "reason": "All parties signed, validation approved"
}

---

Sub-Resources

Rent Detail

One-to-one with RENT_MODIFICATION amendments. Stores the previous and new rent amounts, calculation method, and optional index references.

Endpoint	Method	Description
/{amendment_id}/rent-detail	POST	Create rent detail
/{amendment_id}/rent-detail	GET	Get rent detail
/{amendment_id}/rent-detail	PUT	Update rent detail
/{amendment_id}/rent-detail	DELETE	Delete rent detail

Rent cap validation (zone tendue): At activation, if the lease has is_subject_to_reference_rent_cap = true, the system validates:

Code
new_amount <= reference_rent_increased_per_m2 x estate.area

If exceeded, activation is blocked with a detailed error citing Art. 17-2.

Example:

Code
{
  "previous_amount": 850.00,
  "new_amount": 875.50,
  "increase_percentage": 3.0,
  "calculation_method": "INDEX_BASED",
  "calculation_details": {
    "index_name": "IRL",
    "quarter": "Q1 2025",
    "value": 143.46
  }
}

Duration Detail

One-to-one with DURATION_MODIFICATION and RENEWAL amendments. Stores the previous and new end dates with the extension type.

Endpoint	Method	Description
/{amendment_id}/duration-detail	POST	Create duration detail
/{amendment_id}/duration-detail	GET	Get duration detail
/{amendment_id}/duration-detail	PUT	Update duration detail
/{amendment_id}/duration-detail	DELETE	Delete duration detail

Validation: For RENEWAL and EXTENSION types, new_end_date must be after previous_end_date. For REDUCTION and EARLY_TERMINATION, an earlier date is allowed.

Example:

Code
{
  "previous_end_date": "2025-12-31",
  "new_end_date": "2028-12-31",
  "extension_type": "RENEWAL",
  "reason_code": "TACIT_RENEWAL",
  "reason_details": "Lease renewed by tacit agreement"
}

Validations

Multi-role validation workflow. Each amendment can have multiple validation entries (one per role). Mandatory validations must all be APPROVED before the amendment can be activated.

Endpoint	Method	Description
/{amendment_id}/validations	POST	Create validation entry
/{amendment_id}/validations	GET	List all validations
/{amendment_id}/validations/status	GET	Compute aggregate status
/{amendment_id}/validations/{id}	GET	Get validation entry
/{amendment_id}/validations/{id}	PUT	Approve/reject
/{amendment_id}/validations/{id}	DELETE	Delete validation entry

Aggregate status computation:

Condition	Result
No mandatory validations	FULLY_VALIDATED
Any mandatory = REJECTED	REJECTED
All mandatory = APPROVED	FULLY_VALIDATED
Otherwise	PENDING

Validator roles: LEGAL, FINANCIAL, PROPERTY_MANAGER, OWNER, TENANT

Approve a validation:

Code
PUT /{amendment_id}/validations/{validation_id}
{
  "status": "APPROVED",
  "validated_by": "550e8400-e29b-41d4-a716-446655440000",
  "comments": "Approved after review"
}

Documents

Documents attached to an amendment (unsigned drafts, signed copies, supporting documents).

Endpoint	Method	Description
/{amendment_id}/documents	POST	Attach a document
/{amendment_id}/documents	GET	List documents
/{amendment_id}/documents/{id}	GET	Get document
/{amendment_id}/documents/{id}	PUT	Update a document
/{amendment_id}/documents/{id}	DELETE	Delete document
/{amendment_id}/documents/{id}/validate	PUT	Validate a document

Document types: DRAFT, SIGNED_COPY, SUPPORTING_DOCUMENT, NOTICE, CALCULATION_DETAILS, LEGAL_NOTICE

History

Read-only audit trail. Entries are automatically created by the system when changes occur.

Endpoint	Method	Description
/{amendment_id}/history	GET	List all history entries
/{amendment_id}/history/{id}	GET	Get a specific entry

Change types: STATUS_CHANGE, CONTENT_MODIFICATION, VALIDATION_CHANGE, SIGNATURE_UPDATE, DOCUMENT_ADDITION

Notifications

Notifications are auto-created on status transitions and published as events for email delivery.

Endpoint	Method	Description
/{amendment_id}/notifications	GET	List notifications
/{amendment_id}/notifications/{id}	GET	Get notification
/{amendment_id}/notifications/{id}	PUT	Update status (mark read/actioned)
/{amendment_id}/notifications/{id}	DELETE	Delete notification

Auto-generated notifications:

Transition	Notification Type	Recipients
Any -> PENDING_SIGNATURE	SIGNATURE_REQUIRED	All lessees + owner
Any -> REJECTED	AMENDMENT_REJECTED	Creator (owner)
Any -> ACTIVE	AMENDMENT_ACTIVATED	All lessees
Any -> EXPIRED	AMENDMENT_EXPIRING	Creator (owner)

Notification statuses: DRAFT -> SENT -> READ -> ACTIONED (or EXPIRED)

Recipient types: OWNER, LESSEE, VALIDATOR, CREATOR

---

PDF Generation

Code
POST /leases/{lease_id}/amendments/{amendment_id}/generate-pdf

Generates a legal PDF document using Typst templates. The template is auto-selected based on amendment_type:

Amendment Type	Template
RENT_MODIFICATION	Rent revision template (Art. 17-1)
DURATION_MODIFICATION	Duration modification template
TENANT_MODIFICATION	Tenant modification template (3 signature zones)
Other types	Generic amendment template

Returns application/pdf binary content.

---

Electronic Signature

Two-step process using the shared signature infrastructure (Scaleway Topics + DO Global).

Step 1 — Initiate

Code
POST /{amendment_id}/initiate-signature

Code
{
  "initiator_id": "550e8400-e29b-41d4-a716-446655440000",
  "initiator_signer_type": "PROPRIETAIRE"
}

What happens:

1. Generates the amendment PDF (Typst)
2. Uploads to encrypted storage (SSE-C)
3. Creates DocumentSignature with document_type: AMENDMENT
4. Creates SignatureRequest per signer (owner + all lessees)
5. Publishes signature events to external queue
6. Transitions amendment to PENDING_SIGNATURE
7. Creates DRAFT document record

Step 2 — Finalize

Code
POST /{amendment_id}/finalize-signature

Code
{
  "document_signature_id": "...",
  "signed_pdf_url": "https://storage.example.com/signed/amendment_123.pdf"
}

What happens:

1. Updates DocumentSignature to COMPLETED
2. Stores signed PDF URL
3. Transitions amendment to SIGNED
4. Creates SIGNED_COPY document record

---

Complete Workflow Example

Here's the full lifecycle for a rent modification amendment:

Code
1. POST /leases/{id}/amendments
   → Creates amendment (DRAFT), returns amendment_id

2. POST /leases/{id}/amendments/{aid}/rent-detail
   → Attach rent detail (previous_amount, new_amount, calculation_method)

3. POST /leases/{id}/amendments/{aid}/validations
   → Add validation entries if needed (auto-created for some types)

4. PUT /leases/{id}/amendments/{aid}/validations/{vid}
   → Approve/reject each validation

5. GET /leases/{id}/amendments/{aid}/validations/status
   → Check aggregate status is FULLY_VALIDATED

6. POST /leases/{id}/amendments/{aid}/initiate-signature
   → Generates PDF, creates signature requests (DRAFT → PENDING_SIGNATURE)

7. POST /leases/{id}/amendments/{aid}/finalize-signature
   → After all parties sign (PENDING_SIGNATURE → SIGNED)

8. PUT /leases/{id}/amendments/{aid}/status
   { "status": "ACTIVE" }
   → Validates all validations approved
   → Checks rent cap in zone tendue
   → Updates lease rent_amount
   → SIGNED → ACTIVE
   → Sends AMENDMENT_ACTIVATED notifications to lessees

---

Endpoints Summary

All endpoints are prefixed with /leases/{lease_id}.

Method	Path	Description
POST	/amendments	Create amendment
GET	/amendments	List amendments
GET	/amendments/{id}	Get amendment
PUT	/amendments/{id}	Update amendment
DELETE	/amendments/{id}	Delete amendment
PUT	/amendments/{id}/status	Change status
POST	/amendments/{id}/generate-pdf	Generate PDF
POST	/amendments/{id}/initiate-signature	Start signature
POST	/amendments/{id}/finalize-signature	Complete signature
POST	/amendments/{id}/rent-detail	Create rent detail
GET	/amendments/{id}/rent-detail	Get rent detail
PUT	/amendments/{id}/rent-detail	Update rent detail
DELETE	/amendments/{id}/rent-detail	Delete rent detail
POST	/amendments/{id}/duration-detail	Create duration detail
GET	/amendments/{id}/duration-detail	Get duration detail
PUT	/amendments/{id}/duration-detail	Update duration detail
DELETE	/amendments/{id}/duration-detail	Delete duration detail
POST	/amendments/{id}/validations	Create validation
GET	/amendments/{id}/validations	List validations
GET	/amendments/{id}/validations/status	Aggregate status
GET	/amendments/{id}/validations/{vid}	Get validation
PUT	/amendments/{id}/validations/{vid}	Approve/reject
DELETE	/amendments/{id}/validations/{vid}	Delete validation
POST	/amendments/{id}/documents	Attach document
GET	/amendments/{id}/documents	List documents
GET	/amendments/{id}/documents/{did}	Get document
PUT	/amendments/{id}/documents/{did}	Update document
DELETE	/amendments/{id}/documents/{did}	Delete document
PUT	/amendments/{id}/documents/{did}/validate	Validate document
GET	/amendments/{id}/history	List history
GET	/amendments/{id}/history/{eid}	Get history entry
GET	/amendments/{id}/notifications	List notifications
GET	/amendments/{id}/notifications/{nid}	Get notification
PUT	/amendments/{id}/notifications/{nid}	Update notification
DELETE	/amendments/{id}/notifications/{nid}	Delete notification

Total: 36 endpoints