FairePlace Property Management API

Leases

Endpointhttps://api.faireplace.com/api

Lease management

List all leases where the user is a tenant

GET

https://api.faireplace.com/api

/lessee/leases

Retrieves the list of all leases where the authenticated user is associated as an active tenant.

Authentication and authorization

The user must be authenticated with a valid JWT
The auth_user_id (JWT sub claim) must correspond to an existing lessee
Only leases where the user is effectively a tenant are returned
Terminated leases (with a past end_date) are excluded

Required permissions

lessee:leases:read

List all leases where the user is a tenant › Responses

Lessee leases retrieved successfully

object[]

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

GET/lessee/leases

curl --request GET \
  --url https://api.faireplace.com/api/lessee/leases

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "estate_id": "550e8400-e29b-41d4-a716-446655440001",
    "lease_type_id": "550e8400-e29b-41d4-a716-446655440002",
    "reference_number": "BAIL-2024-001",
    "status": "ACTIVE",
    "start_date": "2024-01-01",
    "end_date": "2025-12-31",
    "rent_amount": 1200,
    "rent_frequency": "MONTHLY"
  }
]

application/json

List leases pending signature for the tenant

GET

https://api.faireplace.com/api

/lessee/leases/pending-signatures

Retrieves the list of leases where the user is a tenant and where a signature is pending on their part.

Filtering criteria

The lease must have an initiated signature document
The document status must not be COMPLETED
There must be a signature request of type TENANT with a non-COMPLETED status

Required permissions

lessee:leases:read

List leases pending signature for the tenant › Responses

Leases pending signature list

object[]

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

GET/lessee/leases/pending-signatures

curl --request GET \
  --url https://api.faireplace.com/api/lessee/leases/pending-signatures

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "estate_id": "550e8400-e29b-41d4-a716-446655440001",
    "reference_number": "BAIL-2024-001",
    "status": "ACTIVE",
    "start_date": "2024-01-01",
    "end_date": "2025-12-31",
    "rent_amount": 1200
  }
]

application/json

Get details of a specific lease for the tenant

GET

https://api.faireplace.com/api

/lessee/leases/{id}

Retrieves the full details of a specific lease, only if the authenticated user is a tenant of this lease.

Security validations

Verifies that the user is indeed a tenant of the lease via is_lessee_for_lease
Returns a 403 error if the user is not authorized to access this lease

Required permissions

lessee:leases:read

Get details of a specific lease for the tenant › path Parameters

id

string · uuid · required

Lease ID to retrieve

Example: 550e8400-e29b-41d4-a716-446655440000

Get details of a specific lease for the tenant › Responses

Lease details retrieved successfully

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

GET/lessee/leases/{id}

curl --request GET \
  --url https://api.faireplace.com/api/lessee/leases/:id

Example Responses

No example specified for this content type

application/json

Get signature status of a lease for the tenant

GET

https://api.faireplace.com/api

/lessee/leases/{id}/signature/status

Retrieves the signature status of a specific lease for the authenticated tenant.

Returns:

The signature document status (READY, SIGNING, COMPLETED, FAILED, ARCHIVED)
The signed media ID (signed_media_id) if the document is signed, allowing retrieval of the signed PDF URL
The details of all associated signature requests
Information about the signers and their status

Required permissions

lessee:leases:read

Get signature status of a lease for the tenant › path Parameters

id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

Get signature status of a lease for the tenant › Responses

Signature status retrieved successfully

lease_id

string · uuid

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

document_signature_id

string · uuid

Signature document ID

Example: 550e8400-e29b-41d4-a716-446655440001

status

string · enum

Signature document status

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: SIGNING

signed_media_id

string | null · uuid

Signed PDF media ID (available after full signature completion)

Example: 550e8400-e29b-41d4-a716-446655440002

object[]

Signature requests list

GET/lessee/leases/{id}/signature/status

curl --request GET \
  --url https://api.faireplace.com/api/lessee/leases/:id/signature/status

Example Responses

No example specified for this content type

application/json

Sign a lease as a tenant

POST

https://api.faireplace.com/api

/lessee/leases/{id}/signature/sign

Allows the authenticated tenant to sign a lease by validating the OTP received via SMS/email.

Signing process

The user must have received an OTP via SMS or email
The OTP is validated via the DO Global service
The signature is applied to the PDF document
The signature request status is updated

Security validations

Verifies that the user is indeed a tenant of the lease
Verifies that the person_id derived from the JWT matches the lease signers
Validates the OTP before applying the signature

Required permissions

lessee:leases:sign

Sign a lease as a tenant › path Parameters

id

string · uuid · required

Lease ID to sign

Example: 550e8400-e29b-41d4-a716-446655440000

Sign a lease as a tenant › Request Body

document_signature_id

string · uuid · required

Signature document ID to sign

Example: 550e8400-e29b-41d4-a716-446655440001

otp

string · minLength: 4 · maxLength: 8 · required

OTP code received via SMS or email

Example: 123456

Sign a lease as a tenant › Responses

Signature initiated successfully (asynchronous processing)

success

boolean

Indicates whether the request was accepted

Example: true

message

string

Confirmation message

Example: OTP validation sent to processing queue

document_signature_id

string · uuid

Signature document ID

Example: 550e8400-e29b-41d4-a716-446655440001

signed_media_id

string | null · uuid

Signed PDF media ID (available after processing)

Example: 550e8400-e29b-41d4-a716-446655440002

signed_pdf_url

string | null

Signed PDF URL (available after processing)

Example: https://storage.example.com/signed/lease-550e8400.pdf

POST/lessee/leases/{id}/signature/sign

curl --request POST \
  --url https://api.faireplace.com/api/lessee/leases/:id/signature/sign \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440001",
  "otp": "123456"
}
'

Example Request Body

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440001",
  "otp": "123456"
}

application/json

Example Responses

No example specified for this content type

application/json

Download the signed lease (PDF)

GET

https://api.faireplace.com/api

/lessee/leases/{id}/pdf

Downloads the signed lease PDF, only if the document has been fully signed by all signers.

Required conditions

The signature document must have the status COMPLETED
All signature requests must have the status COMPLETED
The user must be a tenant of the lease

Response format

Content-Type: application/pdf
Content-Disposition: attachment; filename="lease-{id}.pdf"
The file may be encrypted (SSE-C) depending on the security level

Required permissions

lessee:leases:download

Download the signed lease (PDF) › path Parameters

id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

Download the signed lease (PDF) › Responses

Signed lease PDF

string

GET/lessee/leases/{id}/pdf

curl --request GET \
  --url https://api.faireplace.com/api/lessee/leases/:id/pdf

Example Responses

PDF binary content

application/pdf

List lessees associated with a lease

GET

https://api.faireplace.com/api

/leases/{lease_id}/lessees

Retrieves the list of all lease-lessee associations for a specific lease.

List lessees associated with a lease › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

List lessees associated with a lease › Responses

Lease-lessee association list retrieved successfully

object[]

Association of a lessee with a lease

id

string · uuid · required

Unique identifier of the association

Example: 550e8400-e29b-41d4-a716-446655440005

lease_id

string · uuid · required

Associated lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Associated lessee ID

Example: 550e8400-e29b-41d4-a716-446655440001

role_type

string · enum · required

Role of the lessee in the lease

Enum values:

PRIMARY

CO_TENANT

GUARANTOR

Example: PRIMARY

start_date

string · date · required

Start date of the association

Example: 2024-01-01

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

rent_share

number | null · decimal

Rent share for this lessee (if co-tenancy)

Example: 0.5

end_date

string | null · date

End date of the association

Example: 2025-01-01

created_by_amendment_id

string | null · uuid

Amendment ID that created this association

Example: 550e8400-e29b-41d4-a716-446655440002

ended_by_amendment_id

string | null · uuid

Amendment ID that ended this association

Example: 550e8400-e29b-41d4-a716-446655440004

guarantor_max_amount

number | null · decimal

Maximum guaranteed amount (if role = GUARANTOR)

Example: 10000

guarantor_conditions

string | null · maxLength: 1000

Specific guarantee conditions

guarantees_lessee_id

string | null · uuid

Lessee ID guaranteed by this guarantor (if role = GUARANTOR)

Example: 550e8400-e29b-41d4-a716-446655440003

GET/leases/{lease_id}/lessees

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/lessees

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440005",
    "lease_id": "550e8400-e29b-41d4-a716-446655440000",
    "lessee_id": "550e8400-e29b-41d4-a716-446655440001",
    "role_type": "PRIMARY",
    "rent_share": 0.5,
    "start_date": "2024-01-01",
    "end_date": "2025-01-01",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "created_by_amendment_id": "550e8400-e29b-41d4-a716-446655440002",
    "ended_by_amendment_id": "550e8400-e29b-41d4-a716-446655440004",
    "guarantor_max_amount": 10000,
    "guarantor_conditions": {},
    "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
  }
]

application/json

Associate a lessee with a lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/lessees

Creates a new association between a lease and a lessee.

Associate a lessee with a lease › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

Associate a lessee with a lease › Request Body

Data for associating a lessee with a lease

lessee_id

string · uuid · required

Lessee ID to associate

Example: 550e8400-e29b-41d4-a716-446655440001

role_type

string · enum · required

Role of the lessee in the lease

Enum values:

PRIMARY

CO_TENANT

GUARANTOR

Example: PRIMARY

start_date

string · date · required

Start date of the association

Example: 2024-01-01

lease_id

string | null · uuid

Associated lease ID (can be omitted if in the path)

Example: 550e8400-e29b-41d4-a716-446655440000

rent_share

number | null · decimal · min: 0 · max: 1

Rent share for this lessee (if co-tenancy)

Example: 0.5

end_date

string | null · date

End date of the association

Example: 2025-01-01

created_by_amendment_id

string | null · uuid

Amendment ID that created this association

Example: 550e8400-e29b-41d4-a716-446655440002

guarantor_max_amount

number | null · decimal · min: 0

Maximum guaranteed amount (if role = GUARANTOR)

Example: 10000

guarantor_conditions

string | null · maxLength: 1000

Specific guarantee conditions

guarantees_lessee_id

string | null · uuid

Lessee ID guaranteed by this guarantor (if role = GUARANTOR)

Example: 550e8400-e29b-41d4-a716-446655440003

Associate a lessee with a lease › Responses

Lease-lessee association created successfully

Association of a lessee with a lease

id

string · uuid · required

Unique identifier of the association

Example: 550e8400-e29b-41d4-a716-446655440005

lease_id

string · uuid · required

Associated lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Associated lessee ID

Example: 550e8400-e29b-41d4-a716-446655440001

role_type

string · enum · required

Role of the lessee in the lease

Enum values:

PRIMARY

CO_TENANT

GUARANTOR

Example: PRIMARY

start_date

string · date · required

Start date of the association

Example: 2024-01-01

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

rent_share

number | null · decimal

Rent share for this lessee (if co-tenancy)

Example: 0.5

end_date

string | null · date

End date of the association

Example: 2025-01-01

created_by_amendment_id

string | null · uuid

Amendment ID that created this association

Example: 550e8400-e29b-41d4-a716-446655440002

ended_by_amendment_id

string | null · uuid

Amendment ID that ended this association

Example: 550e8400-e29b-41d4-a716-446655440004

guarantor_max_amount

number | null · decimal

Maximum guaranteed amount (if role = GUARANTOR)

Example: 10000

guarantor_conditions

string | null · maxLength: 1000

Specific guarantee conditions

guarantees_lessee_id

string | null · uuid

Lessee ID guaranteed by this guarantor (if role = GUARANTOR)

Example: 550e8400-e29b-41d4-a716-446655440003

POST/leases/{lease_id}/lessees

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/lessees \
  --header 'Content-Type: application/json' \
  --data '
{
  "lease_id": "550e8400-e29b-41d4-a716-446655440000",
  "lessee_id": "550e8400-e29b-41d4-a716-446655440001",
  "role_type": "PRIMARY",
  "rent_share": 0.5,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "created_by_amendment_id": "550e8400-e29b-41d4-a716-446655440002",
  "guarantor_max_amount": 10000,
  "guarantor_conditions": {},
  "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
}
'

Example Request Body

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440000",
  "lessee_id": "550e8400-e29b-41d4-a716-446655440001",
  "role_type": "PRIMARY",
  "rent_share": 0.5,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "created_by_amendment_id": "550e8400-e29b-41d4-a716-446655440002",
  "guarantor_max_amount": 10000,
  "guarantor_conditions": {},
  "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "lease_id": "550e8400-e29b-41d4-a716-446655440000",
  "lessee_id": "550e8400-e29b-41d4-a716-446655440001",
  "role_type": "PRIMARY",
  "rent_share": 0.5,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by_amendment_id": "550e8400-e29b-41d4-a716-446655440002",
  "ended_by_amendment_id": "550e8400-e29b-41d4-a716-446655440004",
  "guarantor_max_amount": 10000,
  "guarantor_conditions": {},
  "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
}

application/json

List active lessees for a lease

GET

https://api.faireplace.com/api

/leases/{lease_id}/lessees/active

Retrieves the list of currently active lessees for a specific lease.

List active lessees for a lease › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

List active lessees for a lease › Responses

Active lessee list retrieved successfully

object[]

Association of a lessee with a lease

id

string · uuid · required

Unique identifier of the association

Example: 550e8400-e29b-41d4-a716-446655440005

lease_id

string · uuid · required

Associated lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Associated lessee ID

Example: 550e8400-e29b-41d4-a716-446655440001

role_type

string · enum · required

Role of the lessee in the lease

Enum values:

PRIMARY

CO_TENANT

GUARANTOR

Example: PRIMARY

start_date

string · date · required

Start date of the association

Example: 2024-01-01

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

rent_share

number | null · decimal

Rent share for this lessee (if co-tenancy)

Example: 0.5

end_date

string | null · date

End date of the association

Example: 2025-01-01

created_by_amendment_id

string | null · uuid

Amendment ID that created this association

Example: 550e8400-e29b-41d4-a716-446655440002

ended_by_amendment_id

string | null · uuid

Amendment ID that ended this association

Example: 550e8400-e29b-41d4-a716-446655440004

guarantor_max_amount

number | null · decimal

Maximum guaranteed amount (if role = GUARANTOR)

Example: 10000

guarantor_conditions

string | null · maxLength: 1000

Specific guarantee conditions

guarantees_lessee_id

string | null · uuid

Lessee ID guaranteed by this guarantor (if role = GUARANTOR)

Example: 550e8400-e29b-41d4-a716-446655440003

GET/leases/{lease_id}/lessees/active

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/lessees/active

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440005",
    "lease_id": "550e8400-e29b-41d4-a716-446655440000",
    "lessee_id": "550e8400-e29b-41d4-a716-446655440001",
    "role_type": "PRIMARY",
    "rent_share": 0.5,
    "start_date": "2024-01-01",
    "end_date": "2025-01-01",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "created_by_amendment_id": "550e8400-e29b-41d4-a716-446655440002",
    "ended_by_amendment_id": "550e8400-e29b-41d4-a716-446655440004",
    "guarantor_max_amount": 10000,
    "guarantor_conditions": {},
    "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
  }
]

application/json

Get a lease-lessee association

GET

https://api.faireplace.com/api

/leases/{lease_id}/lessees/{lessee_id}

Retrieves the details of a specific association between a lease and a lessee.

Get a lease-lessee association › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Unique lease-lessee association ID

Example: 550e8400-e29b-41d4-a716-446655440001

Get a lease-lessee association › Responses

Lease-lessee association retrieved successfully

Association of a lessee with a lease

id

string · uuid · required

Unique identifier of the association

Example: 550e8400-e29b-41d4-a716-446655440005

lease_id

string · uuid · required

Associated lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Associated lessee ID

Example: 550e8400-e29b-41d4-a716-446655440001

role_type

string · enum · required

Role of the lessee in the lease

Enum values:

PRIMARY

CO_TENANT

GUARANTOR

Example: PRIMARY

start_date

string · date · required

Start date of the association

Example: 2024-01-01

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

rent_share

number | null · decimal

Rent share for this lessee (if co-tenancy)

Example: 0.5

end_date

string | null · date

End date of the association

Example: 2025-01-01

created_by_amendment_id

string | null · uuid

Amendment ID that created this association

Example: 550e8400-e29b-41d4-a716-446655440002

ended_by_amendment_id

string | null · uuid

Amendment ID that ended this association

Example: 550e8400-e29b-41d4-a716-446655440004

guarantor_max_amount

number | null · decimal

Maximum guaranteed amount (if role = GUARANTOR)

Example: 10000

guarantor_conditions

string | null · maxLength: 1000

Specific guarantee conditions

guarantees_lessee_id

string | null · uuid

Lessee ID guaranteed by this guarantor (if role = GUARANTOR)

Example: 550e8400-e29b-41d4-a716-446655440003

GET/leases/{lease_id}/lessees/{lessee_id}

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/lessees/:lessee_id

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "lease_id": "550e8400-e29b-41d4-a716-446655440000",
  "lessee_id": "550e8400-e29b-41d4-a716-446655440001",
  "role_type": "PRIMARY",
  "rent_share": 0.5,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by_amendment_id": "550e8400-e29b-41d4-a716-446655440002",
  "ended_by_amendment_id": "550e8400-e29b-41d4-a716-446655440004",
  "guarantor_max_amount": 10000,
  "guarantor_conditions": {},
  "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
}

application/json

Update a lease-lessee association

PUT

https://api.faireplace.com/api

/leases/{lease_id}/lessees/{lessee_id}

Updates the information of a specific association between a lease and a lessee.

Update a lease-lessee association › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Unique lease-lessee association ID

Example: 550e8400-e29b-41d4-a716-446655440001

Update a lease-lessee association › Request Body

Data for updating a lessee-lease association

role_type

string · enum

Role of the lessee in the lease

Enum values:

PRIMARY

CO_TENANT

GUARANTOR

Example: PRIMARY

rent_share

number | null · decimal · min: 0 · max: 1

Rent share for this lessee (if co-tenancy)

Example: 0.6

end_date

string | null · date

End date of the association

Example: 2025-06-30

ended_by_amendment_id

string | null · uuid

Amendment ID that ended this association

Example: 550e8400-e29b-41d4-a716-446655440004

guarantor_max_amount

number | null · decimal · min: 0

Maximum guaranteed amount (if role = GUARANTOR)

Example: 12000

guarantor_conditions

string | null · maxLength: 1000

Specific guarantee conditions

guarantees_lessee_id

string | null · uuid

Lessee ID guaranteed by this guarantor (if role = GUARANTOR)

Example: 550e8400-e29b-41d4-a716-446655440003

Update a lease-lessee association › Responses

Lease-lessee association updated successfully

Association of a lessee with a lease

id

string · uuid · required

Unique identifier of the association

Example: 550e8400-e29b-41d4-a716-446655440005

lease_id

string · uuid · required

Associated lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Associated lessee ID

Example: 550e8400-e29b-41d4-a716-446655440001

role_type

string · enum · required

Role of the lessee in the lease

Enum values:

PRIMARY

CO_TENANT

GUARANTOR

Example: PRIMARY

start_date

string · date · required

Start date of the association

Example: 2024-01-01

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

rent_share

number | null · decimal

Rent share for this lessee (if co-tenancy)

Example: 0.5

end_date

string | null · date

End date of the association

Example: 2025-01-01

created_by_amendment_id

string | null · uuid

Amendment ID that created this association

Example: 550e8400-e29b-41d4-a716-446655440002

ended_by_amendment_id

string | null · uuid

Amendment ID that ended this association

Example: 550e8400-e29b-41d4-a716-446655440004

guarantor_max_amount

number | null · decimal

Maximum guaranteed amount (if role = GUARANTOR)

Example: 10000

guarantor_conditions

string | null · maxLength: 1000

Specific guarantee conditions

guarantees_lessee_id

string | null · uuid

Lessee ID guaranteed by this guarantor (if role = GUARANTOR)

Example: 550e8400-e29b-41d4-a716-446655440003

PUT/leases/{lease_id}/lessees/{lessee_id}

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/lessees/:lessee_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "role_type": "PRIMARY",
  "rent_share": 0.6,
  "end_date": "2025-06-30",
  "ended_by_amendment_id": "550e8400-e29b-41d4-a716-446655440004",
  "guarantor_max_amount": 12000,
  "guarantor_conditions": {},
  "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
}
'

Example Request Body

{
  "role_type": "PRIMARY",
  "rent_share": 0.6,
  "end_date": "2025-06-30",
  "ended_by_amendment_id": "550e8400-e29b-41d4-a716-446655440004",
  "guarantor_max_amount": 12000,
  "guarantor_conditions": {},
  "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "lease_id": "550e8400-e29b-41d4-a716-446655440000",
  "lessee_id": "550e8400-e29b-41d4-a716-446655440001",
  "role_type": "PRIMARY",
  "rent_share": 0.5,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by_amendment_id": "550e8400-e29b-41d4-a716-446655440002",
  "ended_by_amendment_id": "550e8400-e29b-41d4-a716-446655440004",
  "guarantor_max_amount": 10000,
  "guarantor_conditions": {},
  "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
}

application/json

Delete a lease-lessee association

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/lessees/{lessee_id}

Deletes a specific association between a lease and a lessee.

Delete a lease-lessee association › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Unique lease-lessee association ID

Example: 550e8400-e29b-41d4-a716-446655440001

Delete a lease-lessee association › Responses

Lease-lessee association deleted successfully

No data returned

DELETE/leases/{lease_id}/lessees/{lessee_id}

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/lessees/:lessee_id

Example Responses

No example specified for this content type

End a lessee's term

PUT

https://api.faireplace.com/api

/leases/{lease_id}/lessees/{lessee_id}/end

Ends a lessee's association with a lease at a specified date, potentially via an amendment.

End a lessee's term › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Unique lease-lessee association ID

Example: 550e8400-e29b-41d4-a716-446655440001

End a lessee's term › Request Body

Data for ending a lessee's association with a lease

end_date

string · date · required

End date of the association

Example: 2025-01-01

amendment_id

string | null · uuid

Amendment ID that ended this association

Example: 550e8400-e29b-41d4-a716-446655440000

End a lessee's term › Responses

Lessee term updated successfully

Association of a lessee with a lease

id

string · uuid · required

Unique identifier of the association

Example: 550e8400-e29b-41d4-a716-446655440005

lease_id

string · uuid · required

Associated lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

lessee_id

string · uuid · required

Associated lessee ID

Example: 550e8400-e29b-41d4-a716-446655440001

role_type

string · enum · required

Role of the lessee in the lease

Enum values:

PRIMARY

CO_TENANT

GUARANTOR

Example: PRIMARY

start_date

string · date · required

Start date of the association

Example: 2024-01-01

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

rent_share

number | null · decimal

Rent share for this lessee (if co-tenancy)

Example: 0.5

end_date

string | null · date

End date of the association

Example: 2025-01-01

created_by_amendment_id

string | null · uuid

Amendment ID that created this association

Example: 550e8400-e29b-41d4-a716-446655440002

ended_by_amendment_id

string | null · uuid

Amendment ID that ended this association

Example: 550e8400-e29b-41d4-a716-446655440004

guarantor_max_amount

number | null · decimal

Maximum guaranteed amount (if role = GUARANTOR)

Example: 10000

guarantor_conditions

string | null · maxLength: 1000

Specific guarantee conditions

guarantees_lessee_id

string | null · uuid

Lessee ID guaranteed by this guarantor (if role = GUARANTOR)

Example: 550e8400-e29b-41d4-a716-446655440003

PUT/leases/{lease_id}/lessees/{lessee_id}/end

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/lessees/:lessee_id/end \
  --header 'Content-Type: application/json' \
  --data '
{
  "end_date": "2025-01-01",
  "amendment_id": "550e8400-e29b-41d4-a716-446655440000"
}
'

Example Request Body

{
  "end_date": "2025-01-01",
  "amendment_id": "550e8400-e29b-41d4-a716-446655440000"
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "lease_id": "550e8400-e29b-41d4-a716-446655440000",
  "lessee_id": "550e8400-e29b-41d4-a716-446655440001",
  "role_type": "PRIMARY",
  "rent_share": 0.5,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by_amendment_id": "550e8400-e29b-41d4-a716-446655440002",
  "ended_by_amendment_id": "550e8400-e29b-41d4-a716-446655440004",
  "guarantor_max_amount": 10000,
  "guarantor_conditions": {},
  "guarantees_lessee_id": "550e8400-e29b-41d4-a716-446655440003"
}

application/json

List all leases

GET

https://api.faireplace.com/api

/leases

Retrieve all leases for the tenant

List all leases › Responses

Lease list retrieved successfully

object[]

Lease list item (simplified version)

id

string · uuid · required

estate_id

string · uuid · required

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

start_date

string · date · required

rent_amount

number · decimal · required

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

reference_number

string | null

end_date

string | null · date

lessee_name

string | null

Formatted name of the primary tenant (PRIMARY role). Format: 'FirstName LastName' for individuals, 'Business Name' for companies. NULL if no tenant.

estate_name

string | null

Name of the associated property. NULL if property deleted.

place_name

string | null

Name or address of the place where the property is located. NULL if not defined.

deposit_amount

number | null · decimal

Security deposit amount

GET/leases

curl --request GET \
  --url https://api.faireplace.com/api/leases

Example Responses

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "estate_id": "00000000-0000-0000-0000-000000000000",
    "reference_number": {},
    "status": "ACTIVE",
    "start_date": "2024-08-25",
    "end_date": "2024-08-25",
    "rent_amount": 0,
    "rent_frequency": "MONTHLY",
    "lessee_name": {},
    "estate_name": {},
    "place_name": {},
    "deposit_amount": {}
  }
]

application/json

Create a lease

POST

https://api.faireplace.com/api

/leases

Create a new lease for a property.

Automatic rent synchronization with Estate:

Code
 
┌─────────────────────────────────────────────────────────────┐
│  Lease creation (POST /leases)                              │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
            ┌─────────────────────┐
            │ rent_amount provided │
            │ in the DTO?          │
            └─────────────────────┘
             │              │
    YES      │              │      NO
             ▼              ▼
┌──────────────────┐  ┌──────────────────┐
│ Use the DTO      │  │ Retrieve the     │
│ value            │  │ rent_amount from  │
│                  │  │ the Estate        │
│ Synchronize      │  │                   │
│ with Estate      │  │ If Estate has a   │
│ (update)         │  │ rent_amount:      │
│                  │  │ • Use this value  │
│                  │  │                   │
│                  │  │ If Estate has no  │
│                  │  │ rent_amount:      │
│                  │  │ • Use 0.00        │
│                  │  │   (default value) │
└──────────────────┘  └──────────────────┘
             │              │
             └──────┬───────┘
                    ▼
           ┌─────────────────┐
           │ Create the lease │
           │ with rent_amount │
           └─────────────────┘

Rules:

If rent_amount is provided in the DTO → used for the lease AND synchronized with the Estate
If rent_amount is not provided → uses Estate.rent_amount (or 0.00 if absent)
This synchronization ensures consistency between the lease rent and the property's reference rent

Usage examples:

Create a lease with a specific rent: provide rent_amount: 1200.00 → the lease will be created with this amount and the Estate will be updated
Create a lease using the Estate's reference rent: omit rent_amount or provide null → the system will use estate.rent_amount (or 0.00 if absent)

Create a lease › Request Body

Data for creating a new lease

estate_id

string · uuid · required

Rented property unit ID

lease_type_id

string · uuid · required

Lease type ID

start_date

string · date · required

Lease start date

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Default: 1

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

template_id

string | null · uuid

Template used ID

agent_id

string | null · uuid

Agent ID

reference_number

string | null · maxLength: 500

Lease reference number

end_date

string | null · date

Lease end date

rent_amount

number | null · decimal · min: 0

Rent amount.

Synchronization rules with Estate:

1. When creating a lease (POST /leases):

Code
 
┌─────────────────────────────────────────────────────────────┐
│  Lease creation                                             │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
            ┌─────────────────────┐
            │ rent_amount provided │
            │ in the DTO?         │
            └─────────────────────┘
             │              │
    YES      │              │      NO
             ▼              ▼
┌──────────────────┐  ┌──────────────────┐
│ Use the DTO      │  │ Retrieve the     │
│ value            │  │ rent_amount from  │
│                  │  │ the Estate        │
│                  │  │                  │
│ Synchronize      │  │ If Estate has a  │
│ with Estate      │  │ rent_amount:     │
│ (update)         │  │ • Use this       │
│                  │  │   value          │
│                  │  │                  │
│                  │  │ If Estate has   │
│                  │  │ no              │
│                  │  │ rent_amount:    │
│                  │  │ • Use 0.00      │
│                  │  │   (default      │
│                  │  │   value)        │
└──────────────────┘  └──────────────────┘
             │              │
             └──────┬───────┘
                    ▼
           ┌─────────────────┐
           │ Create the lease │
           │ with rent_amount │
           └─────────────────┘

2. When updating a lease (PUT /leases/{id}):

Code
 
┌─────────────────────────────────────────────────────────────┐
│  Lease update                                               │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
            ┌─────────────────────┐
            │ rent_amount provided │
            │ in the DTO?         │
            └─────────────────────┘
             │              │
    YES      │              │      NO
             ▼              ▼
┌──────────────────┐  ┌──────────────────┐
│ Update the lease │  │ No               │
│ with the new     │  │ synchronization  │
│ value            │  │ (rent_amount     │
│                  │  │ unchanged)       │
│                  │  │                  │
│ Synchronize      │  │                  │
│ with Estate      │  │                  │
│ (update)         │  │                  │
└──────────────────┘  └──────────────────┘

3. When updating rent (PUT /leases/{id}/rent):

Code
 
┌─────────────────────────────────────────────────────────────┐
│  Rent update                                                │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
           ┌─────────────────────┐
           │ Update the lease    │
           │ rent_amount with    │
           │ new_rent_amount     │
           └─────────────────────┘
                      │
                      ▼
           ┌─────────────────────┐
           │ Automatically       │
           │ synchronize with    │
           │ Estate.rent_amount  │
           └─────────────────────┘

Rules summary:

Operation	rent_amount provided?	Estate.rent_amount exists?	Behavior
Creation	Yes	-	Use the DTO value + synchronize with Estate
Creation	No	Yes	Use `Estate.rent_amount`
Creation	No	No	Use `0.00` (default value)
Update	Yes	-	Update the lease + synchronize with Estate
Update	No	-	No rent modification
Rent update	Yes (required)	-	Update the lease + synchronize with Estate

Automatic synchronization:

Synchronization is performed atomically during each operation
It maintains consistency between the lease rent and the property's reference rent
Synchronization is unidirectional: Lease -> Estate (the lease updates the Estate)

Usage examples:

Create a lease with a specific rent: provide rent_amount: 1200.00 -> the lease will be created with this amount AND the Estate will be updated
Create a lease using the Estate's reference rent: omit rent_amount or provide null -> the system will use estate.rent_amount (or 0.00 if absent)

Example: 1200

deposit_amount

number | null · decimal · min: 0

Security deposit amount

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

next_revision_date

string | null · date

Next revision date

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

notes

string | null · maxLength: 5000

Internal notes

is_subject_to_rent_evolution_decree

boolean | null

Subject to rent evolution decree

Default: false

is_subject_to_reference_rent_cap

boolean | null

Subject to increased reference rent cap

Default: false

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

base_rent_amount

number | null · decimal

Base rent

rent_complement_amount

number | null · decimal

Rent supplement

rent_complement_justification

string | null · maxLength: 5000

Supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter

irl_reference_value

number | null · decimal

IRL reference value

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Compliance status

rent_regulation_last_check

string | null · date-time

Last check date

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal · min: 0

Rent increase amount due to landlord's work

rent_increase_work_description

string | null · maxLength: 2000

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal · min: 0

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null · maxLength: 500

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null · maxLength: 500

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null · min: 1

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal · min: 0

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null · maxLength: 2000

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal · min: 0

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null · maxLength: 2000

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null · maxLength: 2000

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null · min: 1

Application duration in months

solidarity_clause

string | null · maxLength: 5000

Solidarity clause between co-tenants

termination_clause

string | null · maxLength: 5000

Termination clause (termination conditions)

visit_clause

string | null · maxLength: 2000

Clause for visits to re-let or sell

furniture_provision_clause

string | null · maxLength: 2000

Clause regarding provided furniture

pet_clause

string | null · maxLength: 2000

Pet clause

insurance_clause

string | null · maxLength: 2000

Tenant home insurance clause

maintenance_clause

string | null · maxLength: 2000

Annual appliance maintenance clause

damage_clause

string | null · maxLength: 2000

Tenant damage clause

regularization_waiver_clause

string | null · maxLength: 3000

Charge regularization waiver clause

rent_free_clause

string | null · maxLength: 5000

Rent-free clause

custom_clause

string | null · maxLength: 5000

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal · min: 0

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal · min: 0

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal · min: 0

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal · min: 0

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null · maxLength: 5000

Details of services performed

landlord_fees_inventory_entry

number | null · decimal · min: 0

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null · maxLength: 5000

Move-in inspection service details

landlord_fees_other

number | null · decimal · min: 0

Other services

landlord_fees_other_description

string | null · maxLength: 5000

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal · min: 0

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null · maxLength: 5000

Details of services performed

tenant_fees_inventory_entry

number | null · decimal · min: 0

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null · maxLength: 5000

Move-in inspection service details

tenant_fees_other

number | null · decimal · min: 0

Other fees

tenant_fees_other_description

string | null · maxLength: 5000

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null · maxLength: 255

Agency/professional name

fees_agency_registration_number

string | null · maxLength: 500

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease, validated by CHECK constraint in database)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

Create a lease › Responses

Lease created successfully

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

POST/leases

curl --request POST \
  --url https://api.faireplace.com/api/leases \
  --header 'Content-Type: application/json' \
  --data '
{
  "estate_id": "00000000-0000-0000-0000-000000000000",
  "lease_type_id": "00000000-0000-0000-0000-000000000000",
  "template_id": "00000000-0000-0000-0000-000000000000",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "reference_number": {},
  "start_date": "2024-08-25",
  "end_date": "2024-08-25",
  "rent_amount": 1200,
  "rent_frequency": "MONTHLY",
  "deposit_amount": {},
  "revision_index_type": "IRL",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "notes": {},
  "is_subject_to_rent_evolution_decree": {},
  "is_subject_to_reference_rent_cap": {},
  "reference_rent_per_m2": {},
  "reference_rent_increased_per_m2": {},
  "base_rent_amount": {},
  "rent_complement_amount": {},
  "rent_complement_justification": {},
  "previous_tenant_last_rent": {},
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": {},
  "irl_reference_value": {},
  "rent_regulation_applied_at": "2024-08-25T15:00:00Z",
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "rent_regulation_last_check": "2024-08-25T15:00:00Z",
  "charge_settlement_mode": "PROVISION",
  "payment_day": 0,
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "rent_increase_for_work": {},
  "rent_increase_work_description": {},
  "rent_increase_work_cost": {},
  "rent_increase_work_completion_date": "2024-08-25",
  "rent_increase_legal_basis": {},
  "rent_increase_calculation_method": {},
  "rent_increase_supporting_documents": {},
  "rent_increase_start_date": "2024-08-25",
  "rent_increase_end_date": "2024-08-25",
  "rent_increase_duration_months": {},
  "rent_decrease_for_tenant_work": {},
  "rent_decrease_work_description": {},
  "rent_decrease_work_estimated_cost": {},
  "rent_decrease_work_deadline": "2024-08-25",
  "rent_decrease_work_specifications": {},
  "rent_decrease_work_authorization_required": {},
  "rent_decrease_restitution_clause": {},
  "rent_decrease_supporting_documents": {},
  "rent_decrease_start_date": "2024-08-25",
  "rent_decrease_end_date": "2024-08-25",
  "rent_decrease_duration_months": {},
  "solidarity_clause": {},
  "termination_clause": {},
  "visit_clause": {},
  "furniture_provision_clause": {},
  "pet_clause": {},
  "insurance_clause": {},
  "maintenance_clause": {},
  "damage_clause": {},
  "regularization_waiver_clause": {},
  "rent_free_clause": {},
  "custom_clause": {},
  "rent_free_start_date": "2024-08-25",
  "rent_free_end_date": "2024-08-25",
  "rent_free_amount": {},
  "tenant_fees_cap_visit_dossier_lease_per_m2": {},
  "tenant_fees_cap_inventory_per_m2": {},
  "landlord_fees_visit_dossier_lease": {},
  "landlord_fees_visit_dossier_lease_description": {},
  "landlord_fees_inventory_entry": {},
  "landlord_fees_inventory_entry_description": {},
  "landlord_fees_other": {},
  "landlord_fees_other_description": {},
  "tenant_fees_visit_dossier_lease": {},
  "tenant_fees_visit_dossier_lease_description": {},
  "tenant_fees_inventory_entry": {},
  "tenant_fees_inventory_entry_description": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_calculation_date": "2024-08-25T15:00:00Z",
  "fees_regulation_compliance": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": [
    {
      "date": "2025-06-01",
      "activity": "Sale of IT accessories",
      "approved_by": "Jean Dupont"
    }
  ],
  "commercial_despecialization_full": {
    "date": "2026-03-15",
    "old_activity": "IT retail",
    "new_activity": "Restaurant",
    "approved": true,
    "indemnity_amount": 15000
  },
  "commercial_guarantors": [
    {
      "name": "Holding Company XYZ",
      "siret": "98765432109876",
      "address": "10 Avenue des Champs-Élysées, 75008 Paris",
      "guaranteed_amount": 50000,
      "signature_date": "2025-01-01"
    }
  ],
  "commercial_insurance_policy": "POL-RC-2025-789456"
}
'

Example Request Body

{
  "estate_id": "00000000-0000-0000-0000-000000000000",
  "lease_type_id": "00000000-0000-0000-0000-000000000000",
  "template_id": "00000000-0000-0000-0000-000000000000",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "reference_number": {},
  "start_date": "2024-08-25",
  "end_date": "2024-08-25",
  "rent_amount": 1200,
  "rent_frequency": "MONTHLY",
  "deposit_amount": {},
  "revision_index_type": "IRL",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "notes": {},
  "is_subject_to_rent_evolution_decree": {},
  "is_subject_to_reference_rent_cap": {},
  "reference_rent_per_m2": {},
  "reference_rent_increased_per_m2": {},
  "base_rent_amount": {},
  "rent_complement_amount": {},
  "rent_complement_justification": {},
  "previous_tenant_last_rent": {},
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": {},
  "irl_reference_value": {},
  "rent_regulation_applied_at": "2024-08-25T15:00:00Z",
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "rent_regulation_last_check": "2024-08-25T15:00:00Z",
  "charge_settlement_mode": "PROVISION",
  "payment_day": 0,
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "rent_increase_for_work": {},
  "rent_increase_work_description": {},
  "rent_increase_work_cost": {},
  "rent_increase_work_completion_date": "2024-08-25",
  "rent_increase_legal_basis": {},
  "rent_increase_calculation_method": {},
  "rent_increase_supporting_documents": {},
  "rent_increase_start_date": "2024-08-25",
  "rent_increase_end_date": "2024-08-25",
  "rent_increase_duration_months": {},
  "rent_decrease_for_tenant_work": {},
  "rent_decrease_work_description": {},
  "rent_decrease_work_estimated_cost": {},
  "rent_decrease_work_deadline": "2024-08-25",
  "rent_decrease_work_specifications": {},
  "rent_decrease_work_authorization_required": {},
  "rent_decrease_restitution_clause": {},
  "rent_decrease_supporting_documents": {},
  "rent_decrease_start_date": "2024-08-25",
  "rent_decrease_end_date": "2024-08-25",
  "rent_decrease_duration_months": {},
  "solidarity_clause": {},
  "termination_clause": {},
  "visit_clause": {},
  "furniture_provision_clause": {},
  "pet_clause": {},
  "insurance_clause": {},
  "maintenance_clause": {},
  "damage_clause": {},
  "regularization_waiver_clause": {},
  "rent_free_clause": {},
  "custom_clause": {},
  "rent_free_start_date": "2024-08-25",
  "rent_free_end_date": "2024-08-25",
  "rent_free_amount": {},
  "tenant_fees_cap_visit_dossier_lease_per_m2": {},
  "tenant_fees_cap_inventory_per_m2": {},
  "landlord_fees_visit_dossier_lease": {},
  "landlord_fees_visit_dossier_lease_description": {},
  "landlord_fees_inventory_entry": {},
  "landlord_fees_inventory_entry_description": {},
  "landlord_fees_other": {},
  "landlord_fees_other_description": {},
  "tenant_fees_visit_dossier_lease": {},
  "tenant_fees_visit_dossier_lease_description": {},
  "tenant_fees_inventory_entry": {},
  "tenant_fees_inventory_entry_description": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_calculation_date": "2024-08-25T15:00:00Z",
  "fees_regulation_compliance": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": [
    {
      "date": "2025-06-01",
      "activity": "Sale of IT accessories",
      "approved_by": "Jean Dupont"
    }
  ],
  "commercial_despecialization_full": {
    "date": "2026-03-15",
    "old_activity": "IT retail",
    "new_activity": "Restaurant",
    "approved": true,
    "indemnity_amount": 15000
  },
  "commercial_guarantors": [
    {
      "name": "Holding Company XYZ",
      "siret": "98765432109876",
      "address": "10 Avenue des Champs-Élysées, 75008 Paris",
      "guaranteed_amount": 50000,
      "signature_date": "2025-01-01"
    }
  ],
  "commercial_insurance_policy": "POL-RC-2025-789456"
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "estate_id": "550e8400-e29b-41d4-a716-446655440001",
  "lease_type_id": "550e8400-e29b-41d4-a716-446655440002",
  "template_id": "00000000-0000-0000-0000-000000000000",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "reference_number": "BAIL-2024-001",
  "status": "ACTIVE",
  "version": 1,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "rent_amount": 1200,
  "rent_frequency": "MONTHLY",
  "deposit_amount": 1200,
  "revision_index_type": "IRL",
  "last_revision_date": "2024-08-25",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "furniture_list_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "is_subject_to_rent_evolution_decree": true,
  "is_subject_to_reference_rent_cap": true,
  "reference_rent_per_m2": 20.5,
  "reference_rent_increased_per_m2": 22.55,
  "base_rent_amount": 1000,
  "rent_complement_amount": 200,
  "rent_complement_justification": {},
  "previous_tenant_last_rent": 1150,
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": "T1 2024",
  "irl_reference_value": 142.35,
  "rent_regulation_applied_at": "2024-08-25T15:00:00Z",
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "rent_regulation_last_check": "2024-08-25T15:00:00Z",
  "charge_settlement_mode": "PROVISION",
  "payment_day": 5,
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "rent_increase_for_work": {},
  "rent_increase_work_description": {},
  "rent_increase_work_cost": {},
  "rent_increase_work_completion_date": "2024-08-25",
  "rent_increase_legal_basis": {},
  "rent_increase_calculation_method": {},
  "rent_increase_supporting_documents": {},
  "rent_increase_start_date": "2024-08-25",
  "rent_increase_end_date": "2024-08-25",
  "rent_increase_duration_months": {},
  "rent_decrease_for_tenant_work": {},
  "rent_decrease_work_description": {},
  "rent_decrease_work_estimated_cost": {},
  "rent_decrease_work_deadline": "2024-08-25",
  "rent_decrease_work_specifications": {},
  "rent_decrease_work_authorization_required": {},
  "rent_decrease_restitution_clause": {},
  "rent_decrease_supporting_documents": {},
  "rent_decrease_start_date": "2024-08-25",
  "rent_decrease_end_date": "2024-08-25",
  "rent_decrease_duration_months": {},
  "solidarity_clause": {},
  "termination_clause": {},
  "visit_clause": {},
  "furniture_provision_clause": {},
  "pet_clause": {},
  "insurance_clause": {},
  "maintenance_clause": {},
  "damage_clause": {},
  "regularization_waiver_clause": {},
  "rent_free_clause": {},
  "custom_clause": {},
  "rent_free_start_date": "2024-08-25",
  "rent_free_end_date": "2024-08-25",
  "rent_free_amount": {},
  "tenant_fees_cap_visit_dossier_lease_per_m2": {},
  "tenant_fees_cap_inventory_per_m2": {},
  "landlord_fees_visit_dossier_lease": {},
  "landlord_fees_visit_dossier_lease_description": {},
  "landlord_fees_inventory_entry": {},
  "landlord_fees_inventory_entry_description": {},
  "landlord_fees_other": {},
  "landlord_fees_other_description": {},
  "tenant_fees_visit_dossier_lease": {},
  "tenant_fees_visit_dossier_lease_description": {},
  "tenant_fees_inventory_entry": {},
  "tenant_fees_inventory_entry_description": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_calculation_date": "2024-08-25T15:00:00Z",
  "fees_regulation_compliance": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": [
    {
      "date": "2025-06-01",
      "activity": "Sale of IT accessories",
      "approved_by": "Jean Dupont"
    }
  ],
  "commercial_despecialization_full": {
    "date": "2026-03-15",
    "old_activity": "IT retail",
    "new_activity": "Restaurant",
    "approved": true,
    "indemnity_amount": 15000
  },
  "commercial_guarantors": [
    {
      "name": "Holding Company XYZ",
      "siret": "98765432109876",
      "address": "10 Avenue des Champs-Élysées, 75008 Paris",
      "guaranteed_amount": 50000,
      "signature_date": "2025-01-01"
    }
  ],
  "commercial_insurance_policy": "POL-RC-2025-789456",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

application/json

Get lease

GET

https://api.faireplace.com/api

/leases/{lease_id}

Retrieve details of a specific lease

Get lease › path Parameters

lease_id

string · uuid · required

Lease ID

Get lease › Responses

Lease retrieved successfully

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

GET/leases/{lease_id}

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "estate_id": "550e8400-e29b-41d4-a716-446655440001",
  "lease_type_id": "550e8400-e29b-41d4-a716-446655440002",
  "template_id": "00000000-0000-0000-0000-000000000000",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "reference_number": "BAIL-2024-001",
  "status": "ACTIVE",
  "version": 1,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "rent_amount": 1200,
  "rent_frequency": "MONTHLY",
  "deposit_amount": 1200,
  "revision_index_type": "IRL",
  "last_revision_date": "2024-08-25",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "furniture_list_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "is_subject_to_rent_evolution_decree": true,
  "is_subject_to_reference_rent_cap": true,
  "reference_rent_per_m2": 20.5,
  "reference_rent_increased_per_m2": 22.55,
  "base_rent_amount": 1000,
  "rent_complement_amount": 200,
  "rent_complement_justification": {},
  "previous_tenant_last_rent": 1150,
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": "T1 2024",
  "irl_reference_value": 142.35,
  "rent_regulation_applied_at": "2024-08-25T15:00:00Z",
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "rent_regulation_last_check": "2024-08-25T15:00:00Z",
  "charge_settlement_mode": "PROVISION",
  "payment_day": 5,
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "rent_increase_for_work": {},
  "rent_increase_work_description": {},
  "rent_increase_work_cost": {},
  "rent_increase_work_completion_date": "2024-08-25",
  "rent_increase_legal_basis": {},
  "rent_increase_calculation_method": {},
  "rent_increase_supporting_documents": {},
  "rent_increase_start_date": "2024-08-25",
  "rent_increase_end_date": "2024-08-25",
  "rent_increase_duration_months": {},
  "rent_decrease_for_tenant_work": {},
  "rent_decrease_work_description": {},
  "rent_decrease_work_estimated_cost": {},
  "rent_decrease_work_deadline": "2024-08-25",
  "rent_decrease_work_specifications": {},
  "rent_decrease_work_authorization_required": {},
  "rent_decrease_restitution_clause": {},
  "rent_decrease_supporting_documents": {},
  "rent_decrease_start_date": "2024-08-25",
  "rent_decrease_end_date": "2024-08-25",
  "rent_decrease_duration_months": {},
  "solidarity_clause": {},
  "termination_clause": {},
  "visit_clause": {},
  "furniture_provision_clause": {},
  "pet_clause": {},
  "insurance_clause": {},
  "maintenance_clause": {},
  "damage_clause": {},
  "regularization_waiver_clause": {},
  "rent_free_clause": {},
  "custom_clause": {},
  "rent_free_start_date": "2024-08-25",
  "rent_free_end_date": "2024-08-25",
  "rent_free_amount": {},
  "tenant_fees_cap_visit_dossier_lease_per_m2": {},
  "tenant_fees_cap_inventory_per_m2": {},
  "landlord_fees_visit_dossier_lease": {},
  "landlord_fees_visit_dossier_lease_description": {},
  "landlord_fees_inventory_entry": {},
  "landlord_fees_inventory_entry_description": {},
  "landlord_fees_other": {},
  "landlord_fees_other_description": {},
  "tenant_fees_visit_dossier_lease": {},
  "tenant_fees_visit_dossier_lease_description": {},
  "tenant_fees_inventory_entry": {},
  "tenant_fees_inventory_entry_description": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_calculation_date": "2024-08-25T15:00:00Z",
  "fees_regulation_compliance": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": [
    {
      "date": "2025-06-01",
      "activity": "Sale of IT accessories",
      "approved_by": "Jean Dupont"
    }
  ],
  "commercial_despecialization_full": {
    "date": "2026-03-15",
    "old_activity": "IT retail",
    "new_activity": "Restaurant",
    "approved": true,
    "indemnity_amount": 15000
  },
  "commercial_guarantors": [
    {
      "name": "Holding Company XYZ",
      "siret": "98765432109876",
      "address": "10 Avenue des Champs-Élysées, 75008 Paris",
      "guaranteed_amount": 50000,
      "signature_date": "2025-01-01"
    }
  ],
  "commercial_insurance_policy": "POL-RC-2025-789456",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

application/json

Update lease

PUT

https://api.faireplace.com/api

/leases/{lease_id}

Update the information of an existing lease.

Automatic rent synchronization with Estate:

Code
 
┌─────────────────────────────────────────────────────────────┐
│  Lease update (PUT /leases/{id})                             │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
            ┌─────────────────────┐
            │ rent_amount provided │
            │ in the DTO?          │
            └─────────────────────┘
             │              │
    YES      │              │      NO
             ▼              ▼
┌──────────────────┐  ┌──────────────────┐
│ Update the lease │  │ No               │
│ with the new     │  │ synchronization  │
│ value            │  │ (rent_amount     │
│                  │  │ unchanged)       │
│ Synchronize      │  │                  │
│ with Estate      │  │                  │
│ (update)         │  │                  │
└──────────────────┘  └──────────────────┘

If rent_amount is provided in the update DTO, it automatically updates the rent_amount of the associated Estate
This synchronization ensures consistency between the lease rent and the property's reference rent
The synchronization is performed atomically during the lease update

Update lease › path Parameters

lease_id

string · uuid · required

Lease ID

Update lease › Request Body

Data for updating a lease (all fields are optional)

reference_number

string | null · maxLength: 500

end_date

string | null · date

rent_amount

number | null · decimal · min: 0

Rent amount.

Synchronization with Estate:

Code
 
┌─────────────────────────────────────────────────────────────┐
│  Lease rent_amount update                                   │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
            ┌─────────────────────┐
            │ rent_amount provided │
            │ in the DTO?         │
            └─────────────────────┘
             │              │
    YES      │              │      NO
             ▼              ▼
┌──────────────────┐  ┌──────────────────┐
│ Update the lease │  │ No               │
│ with the new     │  │ modification     │
│ value            │  │ (rent_amount     │
│                  │  │ unchanged)       │
│                  │  │                  │
│ Synchronize      │  │                  │
│ with Estate      │  │                  │
│ (update)         │  │                  │
└──────────────────┘  └──────────────────┘

If this field is provided during the update, it automatically updates the rent_amount of the associated Estate
This synchronization maintains consistency between the lease rent and the property's reference rent
Synchronization is performed atomically during the lease update

Example: 1200

deposit_amount

number | null · decimal · min: 0

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

next_revision_date

string | null · date

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

notes

string | null · maxLength: 5000

is_subject_to_rent_evolution_decree

boolean | null

is_subject_to_reference_rent_cap

boolean | null

reference_rent_per_m2

number | null · decimal

reference_rent_increased_per_m2

number | null · decimal

base_rent_amount

number | null · decimal

rent_complement_amount

number | null · decimal

rent_complement_justification

string | null · maxLength: 5000

previous_tenant_last_rent

number | null · decimal

previous_tenant_last_payment_date

string | null · date

previous_tenant_last_revision_date

string | null · date

rent_revision_date

string | null · date

irl_reference_quarter

string | null · maxLength: 50

irl_reference_value

number | null · decimal

rent_regulation_zone_type

string | null · maxLength: 50

rent_regulation_compliance_status

string | null · maxLength: 20

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

payment_day

integer | null · min: 1 · max: 31

payment_terms

string · enum

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

landlord_fees_excluding_tax

number | null · decimal

landlord_fees_including_tax

number | null · decimal

tenant_fees_excluding_tax

number | null · decimal

tenant_fees_including_tax

number | null · decimal

tenant_fees_state_of_play

number | null · decimal

tenant_fees_inventory

number | null · decimal

tenant_fees_visit

number | null · decimal

tenant_fees_file_processing

number | null · decimal

tenant_fees_other

number | null · decimal

tenant_fees_other_description

string | null · maxLength: 5000

fees_agency_name

string | null · maxLength: 200

fees_agency_registration_number

string | null · maxLength: 500

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease, validated by CHECK constraint in database)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5)

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49)

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

Update lease › Responses

Lease updated successfully

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

PUT/leases/{lease_id}

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference_number": {},
  "end_date": "2024-08-25",
  "rent_amount": 1200,
  "deposit_amount": {},
  "revision_index_type": "IRL",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "furniture_list_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "is_subject_to_rent_evolution_decree": {},
  "is_subject_to_reference_rent_cap": {},
  "reference_rent_per_m2": {},
  "reference_rent_increased_per_m2": {},
  "base_rent_amount": {},
  "rent_complement_amount": {},
  "rent_complement_justification": {},
  "previous_tenant_last_rent": {},
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": {},
  "irl_reference_value": {},
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "charge_settlement_mode": "PROVISION",
  "payment_day": {},
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "landlord_fees_excluding_tax": {},
  "landlord_fees_including_tax": {},
  "tenant_fees_excluding_tax": {},
  "tenant_fees_including_tax": {},
  "tenant_fees_state_of_play": {},
  "tenant_fees_inventory": {},
  "tenant_fees_visit": {},
  "tenant_fees_file_processing": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": {},
  "commercial_despecialization_full": {},
  "commercial_guarantors": {},
  "commercial_insurance_policy": "POL-RC-2025-789456"
}
'

Example Request Body

{
  "reference_number": {},
  "end_date": "2024-08-25",
  "rent_amount": 1200,
  "deposit_amount": {},
  "revision_index_type": "IRL",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "furniture_list_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "is_subject_to_rent_evolution_decree": {},
  "is_subject_to_reference_rent_cap": {},
  "reference_rent_per_m2": {},
  "reference_rent_increased_per_m2": {},
  "base_rent_amount": {},
  "rent_complement_amount": {},
  "rent_complement_justification": {},
  "previous_tenant_last_rent": {},
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": {},
  "irl_reference_value": {},
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "charge_settlement_mode": "PROVISION",
  "payment_day": {},
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "landlord_fees_excluding_tax": {},
  "landlord_fees_including_tax": {},
  "tenant_fees_excluding_tax": {},
  "tenant_fees_including_tax": {},
  "tenant_fees_state_of_play": {},
  "tenant_fees_inventory": {},
  "tenant_fees_visit": {},
  "tenant_fees_file_processing": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": {},
  "commercial_despecialization_full": {},
  "commercial_guarantors": {},
  "commercial_insurance_policy": "POL-RC-2025-789456"
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "estate_id": "550e8400-e29b-41d4-a716-446655440001",
  "lease_type_id": "550e8400-e29b-41d4-a716-446655440002",
  "template_id": "00000000-0000-0000-0000-000000000000",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "reference_number": "BAIL-2024-001",
  "status": "ACTIVE",
  "version": 1,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "rent_amount": 1200,
  "rent_frequency": "MONTHLY",
  "deposit_amount": 1200,
  "revision_index_type": "IRL",
  "last_revision_date": "2024-08-25",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "furniture_list_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "is_subject_to_rent_evolution_decree": true,
  "is_subject_to_reference_rent_cap": true,
  "reference_rent_per_m2": 20.5,
  "reference_rent_increased_per_m2": 22.55,
  "base_rent_amount": 1000,
  "rent_complement_amount": 200,
  "rent_complement_justification": {},
  "previous_tenant_last_rent": 1150,
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": "T1 2024",
  "irl_reference_value": 142.35,
  "rent_regulation_applied_at": "2024-08-25T15:00:00Z",
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "rent_regulation_last_check": "2024-08-25T15:00:00Z",
  "charge_settlement_mode": "PROVISION",
  "payment_day": 5,
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "rent_increase_for_work": {},
  "rent_increase_work_description": {},
  "rent_increase_work_cost": {},
  "rent_increase_work_completion_date": "2024-08-25",
  "rent_increase_legal_basis": {},
  "rent_increase_calculation_method": {},
  "rent_increase_supporting_documents": {},
  "rent_increase_start_date": "2024-08-25",
  "rent_increase_end_date": "2024-08-25",
  "rent_increase_duration_months": {},
  "rent_decrease_for_tenant_work": {},
  "rent_decrease_work_description": {},
  "rent_decrease_work_estimated_cost": {},
  "rent_decrease_work_deadline": "2024-08-25",
  "rent_decrease_work_specifications": {},
  "rent_decrease_work_authorization_required": {},
  "rent_decrease_restitution_clause": {},
  "rent_decrease_supporting_documents": {},
  "rent_decrease_start_date": "2024-08-25",
  "rent_decrease_end_date": "2024-08-25",
  "rent_decrease_duration_months": {},
  "solidarity_clause": {},
  "termination_clause": {},
  "visit_clause": {},
  "furniture_provision_clause": {},
  "pet_clause": {},
  "insurance_clause": {},
  "maintenance_clause": {},
  "damage_clause": {},
  "regularization_waiver_clause": {},
  "rent_free_clause": {},
  "custom_clause": {},
  "rent_free_start_date": "2024-08-25",
  "rent_free_end_date": "2024-08-25",
  "rent_free_amount": {},
  "tenant_fees_cap_visit_dossier_lease_per_m2": {},
  "tenant_fees_cap_inventory_per_m2": {},
  "landlord_fees_visit_dossier_lease": {},
  "landlord_fees_visit_dossier_lease_description": {},
  "landlord_fees_inventory_entry": {},
  "landlord_fees_inventory_entry_description": {},
  "landlord_fees_other": {},
  "landlord_fees_other_description": {},
  "tenant_fees_visit_dossier_lease": {},
  "tenant_fees_visit_dossier_lease_description": {},
  "tenant_fees_inventory_entry": {},
  "tenant_fees_inventory_entry_description": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_calculation_date": "2024-08-25T15:00:00Z",
  "fees_regulation_compliance": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": [
    {
      "date": "2025-06-01",
      "activity": "Sale of IT accessories",
      "approved_by": "Jean Dupont"
    }
  ],
  "commercial_despecialization_full": {
    "date": "2026-03-15",
    "old_activity": "IT retail",
    "new_activity": "Restaurant",
    "approved": true,
    "indemnity_amount": 15000
  },
  "commercial_guarantors": [
    {
      "name": "Holding Company XYZ",
      "siret": "98765432109876",
      "address": "10 Avenue des Champs-Élysées, 75008 Paris",
      "guaranteed_amount": 50000,
      "signature_date": "2025-01-01"
    }
  ],
  "commercial_insurance_policy": "POL-RC-2025-789456",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

application/json

Delete lease

DELETE

https://api.faireplace.com/api

/leases/{lease_id}

Delete an existing lease

Delete lease › path Parameters

lease_id

string · uuid · required

Lease ID

Delete lease › Responses

Lease deleted successfully

No data returned

DELETE/leases/{lease_id}

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id

Example Responses

No example specified for this content type

Change lease status

PUT

https://api.faireplace.com/api

/leases/{lease_id}/status

Change the status of a lease (DRAFT, ACTIVE, NOTICE, FINALISATION, TERMINATED, EXPIRED)

Change lease status › path Parameters

lease_id

string · uuid · required

Lease ID

Change lease status › Request Body

Data for changing a lease status

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

reason

string | null · maxLength: 500

Reason for the status change

Change lease status › Responses

Lease status updated successfully

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

PUT/leases/{lease_id}/status

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/status \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "ACTIVE",
  "reason": {}
}
'

Example Request Body

{
  "status": "ACTIVE",
  "reason": {}
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "estate_id": "550e8400-e29b-41d4-a716-446655440001",
  "lease_type_id": "550e8400-e29b-41d4-a716-446655440002",
  "template_id": "00000000-0000-0000-0000-000000000000",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "reference_number": "BAIL-2024-001",
  "status": "ACTIVE",
  "version": 1,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "rent_amount": 1200,
  "rent_frequency": "MONTHLY",
  "deposit_amount": 1200,
  "revision_index_type": "IRL",
  "last_revision_date": "2024-08-25",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "furniture_list_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "is_subject_to_rent_evolution_decree": true,
  "is_subject_to_reference_rent_cap": true,
  "reference_rent_per_m2": 20.5,
  "reference_rent_increased_per_m2": 22.55,
  "base_rent_amount": 1000,
  "rent_complement_amount": 200,
  "rent_complement_justification": {},
  "previous_tenant_last_rent": 1150,
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": "T1 2024",
  "irl_reference_value": 142.35,
  "rent_regulation_applied_at": "2024-08-25T15:00:00Z",
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "rent_regulation_last_check": "2024-08-25T15:00:00Z",
  "charge_settlement_mode": "PROVISION",
  "payment_day": 5,
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "rent_increase_for_work": {},
  "rent_increase_work_description": {},
  "rent_increase_work_cost": {},
  "rent_increase_work_completion_date": "2024-08-25",
  "rent_increase_legal_basis": {},
  "rent_increase_calculation_method": {},
  "rent_increase_supporting_documents": {},
  "rent_increase_start_date": "2024-08-25",
  "rent_increase_end_date": "2024-08-25",
  "rent_increase_duration_months": {},
  "rent_decrease_for_tenant_work": {},
  "rent_decrease_work_description": {},
  "rent_decrease_work_estimated_cost": {},
  "rent_decrease_work_deadline": "2024-08-25",
  "rent_decrease_work_specifications": {},
  "rent_decrease_work_authorization_required": {},
  "rent_decrease_restitution_clause": {},
  "rent_decrease_supporting_documents": {},
  "rent_decrease_start_date": "2024-08-25",
  "rent_decrease_end_date": "2024-08-25",
  "rent_decrease_duration_months": {},
  "solidarity_clause": {},
  "termination_clause": {},
  "visit_clause": {},
  "furniture_provision_clause": {},
  "pet_clause": {},
  "insurance_clause": {},
  "maintenance_clause": {},
  "damage_clause": {},
  "regularization_waiver_clause": {},
  "rent_free_clause": {},
  "custom_clause": {},
  "rent_free_start_date": "2024-08-25",
  "rent_free_end_date": "2024-08-25",
  "rent_free_amount": {},
  "tenant_fees_cap_visit_dossier_lease_per_m2": {},
  "tenant_fees_cap_inventory_per_m2": {},
  "landlord_fees_visit_dossier_lease": {},
  "landlord_fees_visit_dossier_lease_description": {},
  "landlord_fees_inventory_entry": {},
  "landlord_fees_inventory_entry_description": {},
  "landlord_fees_other": {},
  "landlord_fees_other_description": {},
  "tenant_fees_visit_dossier_lease": {},
  "tenant_fees_visit_dossier_lease_description": {},
  "tenant_fees_inventory_entry": {},
  "tenant_fees_inventory_entry_description": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_calculation_date": "2024-08-25T15:00:00Z",
  "fees_regulation_compliance": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": [
    {
      "date": "2025-06-01",
      "activity": "Sale of IT accessories",
      "approved_by": "Jean Dupont"
    }
  ],
  "commercial_despecialization_full": {
    "date": "2026-03-15",
    "old_activity": "IT retail",
    "new_activity": "Restaurant",
    "approved": true,
    "indemnity_amount": 15000
  },
  "commercial_guarantors": [
    {
      "name": "Holding Company XYZ",
      "siret": "98765432109876",
      "address": "10 Avenue des Champs-Élysées, 75008 Paris",
      "guaranteed_amount": 50000,
      "signature_date": "2025-01-01"
    }
  ],
  "commercial_insurance_policy": "POL-RC-2025-789456",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

application/json

Update lease rent

PUT

https://api.faireplace.com/api

/leases/{lease_id}/rent

Update the rent amount and revision information.

Automatic synchronization with Estate:

Code
 
┌─────────────────────────────────────────────────────────────┐
│  Rent update (PUT /leases/{id}/rent)                          │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
           ┌─────────────────────┐
           │ Update the lease's  │
           │ rent_amount with    │
           │ new_rent_amount     │
           └─────────────────────┘
                      │
                      ▼
           ┌─────────────────────┐
           │ Automatically       │
           │ synchronize with    │
           │ Estate.rent_amount  │
           └─────────────────────┘

The new rent amount (new_rent_amount) is automatically synchronized to the rent_amount field of the associated Estate
This synchronization ensures consistency between the lease rent and the property's reference rent
The synchronization is performed atomically during the rent update

Update lease rent › path Parameters

lease_id

string · uuid · required

Lease ID

Update lease rent › Request Body

Data for updating a lease's rent. **Automatic synchronization with Estate**: ``` ┌─────────────────────────────────────────────────────────────┐ │ Synchronization flow Lease -> Estate │ └─────────────────────────────────────────────────────────────┘ PUT /leases/{id}/rent │ ▼ ┌──────────────────────┐ │ new_rent_amount │ │ (in the DTO) │ └──────────────────────┘ │ ▼ ┌──────────────────────┐ ┌──────────────────────┐ │ Lease rent_amount │────────▶│ Automatic │ │ update │ │ synchronization with │ └──────────────────────┘ │ Estate.rent_amount │ └──────────────────────┘ ``` - The new rent amount (`new_rent_amount`) is automatically synchronized to the `rent_amount` field of the associated Estate - This synchronization maintains consistency between the lease rent and the property's reference rent - Synchronization is performed atomically during the rent update

new_rent_amount

number · decimal · min: 0 · required

New rent amount.

Automatic synchronization:

Code
 
┌─────────────────────────────────────────────────────────────┐
│  Rent update (PUT /leases/{id}/rent)                        │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
           ┌─────────────────────┐
           │ Update the lease    │
           │ rent_amount with    │
           │ new_rent_amount     │
           └─────────────────────┘
                      │
                      ▼
           ┌─────────────────────┐
           │ Automatically       │
           │ synchronize with    │
           │ Estate.rent_amount  │
           └─────────────────────┘

This amount is automatically synchronized to the rent_amount field of the Estate associated with the lease
Synchronization is performed atomically during the update

revision_date

string | null · date

Revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter

irl_reference_value

number | null · decimal

IRL reference value

Update lease rent › Responses

Rent updated successfully

Complete lease

id

string · uuid · required

Unique lease identifier

Example: 550e8400-e29b-41d4-a716-446655440000

estate_id

string · uuid · required

Rented property unit ID

Example: 550e8400-e29b-41d4-a716-446655440001

lease_type_id

string · uuid · required

Lease type ID

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

version

integer · required

Lease version (incremented with each amendment)

Example: 1

start_date

string · date · required

Lease start date

Example: 2024-01-01

rent_amount

number · decimal · required

Lease rent amount (in EUR). Automatically synchronized with the associated Estate's rent_amount.

Example: 1200

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

is_subject_to_rent_evolution_decree

boolean · required

Subject to rent evolution decree at re-letting

Default: false

is_subject_to_reference_rent_cap

boolean · required

Subject to increased reference rent by prefectural decree

Default: false

payment_day

integer · min: 1 · max: 31 · required

Monthly payment day (1-31)

Example: 5

payment_terms

string · enum · required

Payment terms

Enum values:

TERME_ECHU

TERME_A_ECHOIR

Example: TERME_A_ECHOIR

payment_method

string · enum · required

Payment method

Enum values:

VIREMENT_BANCAIRE

PRELEVEMENT_AUTOMATIQUE

CHEQUE

ESPECES

CARTE_BANCAIRE

MANDAT_CASH

AUTRE

Example: VIREMENT_BANCAIRE

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

template_id

string | null · uuid

Template ID used to generate the lease

agent_id

string | null · uuid

Agent ID (real estate agent)

reference_number

string | null · maxLength: 500

Lease reference number

Example: BAIL-2024-001

end_date

string | null · date

Lease end date

Example: 2025-01-01

deposit_amount

number | null · decimal

Security deposit amount

Example: 1200

revision_index_type

string · enum

Rent revision index type

Enum values:

ILC

ILAT

IRL

ICC

NONE

Example: IRL

last_revision_date

string | null · date

Date of the last rent revision

next_revision_date

string | null · date

Date of the next rent revision

usage_type

string · enum

Premises usage type

Enum values:

RESIDENTIAL_ONLY

MIXED_PROFESSIONAL

Example: RESIDENTIAL_ONLY

furniture_list_id

string | null · uuid

Furniture list ID (for furnished leases)

notes

string | null · maxLength: 5000

Internal notes

reference_rent_per_m2

number | null · decimal

Reference rent in EUR/m²

Example: 20.5

reference_rent_increased_per_m2

number | null · decimal

Increased reference rent in EUR/m²

Example: 22.55

base_rent_amount

number | null · decimal

Base rent (equal to increased reference rent if supplement)

Example: 1000

rent_complement_amount

number | null · decimal

Rent supplement

Example: 200

rent_complement_justification

string | null · maxLength: 5000

Rent supplement justification

previous_tenant_last_rent

number | null · decimal

Previous tenant's last rent

Example: 1150

previous_tenant_last_payment_date

string | null · date

Previous tenant's last payment date

previous_tenant_last_revision_date

string | null · date

Previous tenant's last revision date

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null · maxLength: 50

IRL reference quarter (e.g., Q1 2024)

Example: T1 2024

irl_reference_value

number | null · decimal

IRL reference index value

Example: 142.35

rent_regulation_applied_at

string | null · date-time

Regulation application date

rent_regulation_zone_type

string | null · maxLength: 50

Regulation zone type

rent_regulation_compliance_status

string | null · maxLength: 20

Regulation compliance status

rent_regulation_last_check

string | null · date-time

Date of last compliance check

charge_settlement_mode

string · enum

Charge settlement mode

Enum values:

PROVISION

PERIODIC

FLAT_RATE

Example: PROVISION

rent_increase_for_work

number | null · decimal

Rent increase amount due to landlord's work

rent_increase_work_description

string | null

Description of work done by the landlord

rent_increase_work_cost

number | null · decimal

Total cost of work done by the landlord

rent_increase_work_completion_date

string | null · date

Work completion date

rent_increase_legal_basis

string | null

Legal basis (e.g., art. 17-2 law 1989)

rent_increase_calculation_method

string | null

Calculation method used

object | null

Supporting documents (invoices, quotes) - JSON format

rent_increase_start_date

string | null · date

Start date of the rent increase application

rent_increase_end_date

string | null · date

End date of the rent increase application

rent_increase_duration_months

integer | null

Application duration in months

rent_decrease_for_tenant_work

number | null · decimal

Rent decrease amount due to tenant's required work

rent_decrease_work_description

string | null

Description of work to be done by the tenant

rent_decrease_work_estimated_cost

number | null · decimal

Estimated cost of work to be borne by the tenant

rent_decrease_work_deadline

string | null · date

Deadline to complete the work

rent_decrease_work_specifications

string | null

Technical specifications of the work

rent_decrease_work_authorization_required

boolean | null

Prior authorization required

rent_decrease_restitution_clause

string | null

Restitution clause at end of lease

object | null

Documents (quotes, specifications) - JSON format

rent_decrease_start_date

string | null · date

Start date of the rent decrease application

rent_decrease_end_date

string | null · date

End date of the rent decrease application

rent_decrease_duration_months

integer | null

Application duration in months

solidarity_clause

string | null

Solidarity clause between co-tenants

termination_clause

string | null

Termination clause (termination conditions)

visit_clause

string | null

Clause for visits to re-let or sell

furniture_provision_clause

string | null

Clause regarding provided furniture

pet_clause

string | null

Pet clause

insurance_clause

string | null

Tenant home insurance clause

maintenance_clause

string | null

Annual appliance maintenance clause

damage_clause

string | null

Tenant damage clause

regularization_waiver_clause

string | null

Charge regularization waiver clause

rent_free_clause

string | null

Rent-free clause

custom_clause

string | null

Custom clause (free-form)

rent_free_start_date

string | null · date

Rent-free period start date

rent_free_end_date

string | null · date

Rent-free period end date

rent_free_amount

number | null · decimal

Rent-free amount (0 = fully free, >0 = reduced rent)

tenant_fees_cap_visit_dossier_lease_per_m2

number | null · decimal

Fee cap for visits/file processing/lease drafting (EUR/m²)

tenant_fees_cap_inventory_per_m2

number | null · decimal

Fee cap for move-in inspection (EUR/m²)

landlord_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

landlord_fees_visit_dossier_lease_description

string | null

Details of services performed

landlord_fees_inventory_entry

number | null · decimal

Move-in inspection fees

landlord_fees_inventory_entry_description

string | null

Move-in inspection service details

landlord_fees_other

number | null · decimal

Other services

landlord_fees_other_description

string | null

Details of other services and conditions

tenant_fees_visit_dossier_lease

number | null · decimal

Fees for visits/file processing/lease drafting

tenant_fees_visit_dossier_lease_description

string | null

Details of services performed

tenant_fees_inventory_entry

number | null · decimal

Move-in inspection fees

tenant_fees_inventory_entry_description

string | null

Move-in inspection service details

tenant_fees_other

number | null · decimal

Other fees

tenant_fees_other_description

string | null

Details of other services

fees_calculation_date

string | null · date-time

Fee calculation date

fees_regulation_compliance

boolean | null

Regulatory compliance

fees_agency_name

string | null

Agency/professional name

fees_agency_registration_number

string | null

Professional registration number

student_school_name

string | null · maxLength: 200

Educational institution name (student lease only)

Example: Université Paris-Saclay

student_enrollment_year

string | null · maxLength: 10

Academic year (student lease only)

Example: 2024-2025

student_certificate_provided

boolean | null

Enrollment certificate provided (student lease only)

student_level

string | null · maxLength: 50

Education level (student lease only)

Example: Master 1

mobility_reason

string | null · enum

Mobility reason (mobility lease only)

Enum values:

formation_professionnelle

etudes_superieures

contrat_apprentissage

stage

service_civique

mutation_professionnelle

mission_temporaire

autre

Example: mission_temporaire

mobility_reason_other

string | null · maxLength: 500

Reason details if 'autre' (mobility lease only)

initial_duration_months

integer | null · min: 1 · max: 10

Initial duration in months (mobility lease only, between 1 and 10 months)

Example: 6

extended_duration_months

integer | null · min: 1 · max: 10

Duration after extension in months (mobility lease only, maximum 10 months total)

Example: 9

lease_extension_info

object | null

Extension amendment information (mobility lease only)

seasonal_rental_purpose

string | null · maxLength: 100

Seasonal stay reason (seasonal lease only, max duration 90 days). Common values: vacation, business trip, spa treatment, tourism, other.

Example: vacances

seasonal_purpose_details

string | null · maxLength: 2000

Additional reason details if 'other' selected (seasonal lease only)

seasonal_guest_count

integer | null · min: 1

Number of guests accommodated in the property (seasonal lease only, minimum 1 person)

Example: 4

seasonal_cleaning_included

boolean | null

Indicates whether end-of-stay cleaning is included in the rent (seasonal lease only)

Default: false

seasonal_cleaning_fee

number | null · decimal · min: 0

End-of-stay cleaning fee if not included in the rent (seasonal lease only, in EUR)

Example: 80

seasonal_tourist_tax_included

boolean | null

Indicates whether the tourist tax is included in the rent (seasonal lease only)

Default: false

seasonal_tourist_tax_amount

number | null · decimal · min: 0

Tourist tax amount per person per night (seasonal lease only, in EUR)

Example: 2.5

seasonal_services_included

string | null · maxLength: 1000

Services included in the seasonal rental (wifi, household linen, parking, etc.)

Example: WiFi, household linen, private parking

seasonal_energy_mode

string | null · enum

Energy billing mode for the seasonal rental

Enum values:

inclus_forfait

compteur_releve

non_inclus

Example: inclus_forfait

seasonal_cancellation_policy

string | null · maxLength: 2000

Specific cancellation policy defined by the landlord (conditions, deadlines, potential penalties)

seasonal_declaration_number

string | null · maxLength: 50

City hall declaration number (Cerfa n°14004) - Legally required unless the property is the landlord's primary residence (Tourism Code L.324-1-1)

Example: 75001-2025-00123

commercial_business_name

string | null · maxLength: 255

Tenant company business name (commercial lease only, required per Article L145-1)

Example: TECH RETAIL SARL

commercial_legal_form

string | null · maxLength: 100

Company legal form (SARL, SAS, EURL, etc.)

Example: SARL

commercial_siret

string | null · maxLength: 14 · pattern: ^\d{14}$

14-digit SIRET number (required for commercial lease)

Example: 12345678901234

commercial_rcs

string | null · maxLength: 100

RCS registration (e.g., RCS Paris 123 456 789)

Example: RCS Paris 987 654 321

commercial_activity

string | null · maxLength: 2000

Description of the authorized commercial activity (premises purpose, Article L145-1). Determines despecialization rights.

Example: IT retail and office equipment

commercial_activity_code_ape

string | null · maxLength: 10

APE/NAF activity code (e.g., 47.11F)

Example: 47.11F

commercial_triennial_exit_year_3

string | null · date

Notification deadline for triennial termination at year 3 (3-6-9 rule, Article L145-5). The tenant must notify 6 months before this date.

Example: 2027-07-01

commercial_triennial_exit_year_6

string | null · date

Notification deadline for triennial termination at year 6 (3-6-9 rule, Article L145-5)

Example: 2030-07-01

commercial_triennial_exit_year_9

string | null · date

Notification deadline for triennial termination at year 9 (3-6-9 rule, Article L145-5)

Example: 2033-07-01

commercial_notice_period_months

integer | null · min: 1

Termination notice period in months (minimum 6 months per Article L145-12)

Example: 6

commercial_ilc_base_value

number | null · decimal · min: 0

Commercial Rent Index (ILC) reference value at lease start (for triennial revision per Articles L145-33 to L145-38)

Example: 130.52

commercial_ilc_base_date

string | null · date

ILC reference date (quarter) (e.g., 2024-10-01 for Q4 2024)

Example: 2024-10-01

commercial_next_revision_date

string | null · date

Next triennial rent revision date based on ILC

Example: 2027-01-01

commercial_rent_ceiling_enabled

boolean | null

Rent variation capping at +/-10% per 3-year period (Article L145-38)

Default: false

array | null

History of granted partial despecializations (related or complementary activities, Article L145-47)

Example: [{"date":"2025-06-01","activity":"Sale of IT accessories","approved_by":"Jean Dupont"}]

commercial_despecialization_full

object | null

Full despecialization (complete change of activity, Articles L145-48 and L145-49, requires judicial procedure)

Example: {"date":"2026-03-15","old_activity":"IT retail","new_activity":"Restaurant","approved":true,"indemnity_amount":15000}

array | null

Joint and several guarantors for the commercial lease (Article 2298 of the Civil Code)

Example: [{"name":"Holding Company XYZ","siret":"98765432109876","address":"10 Avenue des Champs-Élysées, 75008 Paris","guaranteed_amount":50000,"signature_date":"2025-01-01"}]

commercial_insurance_policy

string | null · maxLength: 200

Insurance policy number for rental risks and professional liability (required per Article L145-7)

Example: POL-RC-2025-789456

PUT/leases/{lease_id}/rent

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/rent \
  --header 'Content-Type: application/json' \
  --data '
{
  "new_rent_amount": 0,
  "revision_date": "2024-08-25",
  "irl_reference_quarter": {},
  "irl_reference_value": {}
}
'

Example Request Body

{
  "new_rent_amount": 0,
  "revision_date": "2024-08-25",
  "irl_reference_quarter": {},
  "irl_reference_value": {}
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "estate_id": "550e8400-e29b-41d4-a716-446655440001",
  "lease_type_id": "550e8400-e29b-41d4-a716-446655440002",
  "template_id": "00000000-0000-0000-0000-000000000000",
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "reference_number": "BAIL-2024-001",
  "status": "ACTIVE",
  "version": 1,
  "start_date": "2024-01-01",
  "end_date": "2025-01-01",
  "rent_amount": 1200,
  "rent_frequency": "MONTHLY",
  "deposit_amount": 1200,
  "revision_index_type": "IRL",
  "last_revision_date": "2024-08-25",
  "next_revision_date": "2024-08-25",
  "usage_type": "RESIDENTIAL_ONLY",
  "furniture_list_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "is_subject_to_rent_evolution_decree": true,
  "is_subject_to_reference_rent_cap": true,
  "reference_rent_per_m2": 20.5,
  "reference_rent_increased_per_m2": 22.55,
  "base_rent_amount": 1000,
  "rent_complement_amount": 200,
  "rent_complement_justification": {},
  "previous_tenant_last_rent": 1150,
  "previous_tenant_last_payment_date": "2024-08-25",
  "previous_tenant_last_revision_date": "2024-08-25",
  "rent_revision_date": "2024-08-25",
  "irl_reference_quarter": "T1 2024",
  "irl_reference_value": 142.35,
  "rent_regulation_applied_at": "2024-08-25T15:00:00Z",
  "rent_regulation_zone_type": {},
  "rent_regulation_compliance_status": {},
  "rent_regulation_last_check": "2024-08-25T15:00:00Z",
  "charge_settlement_mode": "PROVISION",
  "payment_day": 5,
  "payment_terms": "TERME_A_ECHOIR",
  "payment_method": "VIREMENT_BANCAIRE",
  "rent_increase_for_work": {},
  "rent_increase_work_description": {},
  "rent_increase_work_cost": {},
  "rent_increase_work_completion_date": "2024-08-25",
  "rent_increase_legal_basis": {},
  "rent_increase_calculation_method": {},
  "rent_increase_supporting_documents": {},
  "rent_increase_start_date": "2024-08-25",
  "rent_increase_end_date": "2024-08-25",
  "rent_increase_duration_months": {},
  "rent_decrease_for_tenant_work": {},
  "rent_decrease_work_description": {},
  "rent_decrease_work_estimated_cost": {},
  "rent_decrease_work_deadline": "2024-08-25",
  "rent_decrease_work_specifications": {},
  "rent_decrease_work_authorization_required": {},
  "rent_decrease_restitution_clause": {},
  "rent_decrease_supporting_documents": {},
  "rent_decrease_start_date": "2024-08-25",
  "rent_decrease_end_date": "2024-08-25",
  "rent_decrease_duration_months": {},
  "solidarity_clause": {},
  "termination_clause": {},
  "visit_clause": {},
  "furniture_provision_clause": {},
  "pet_clause": {},
  "insurance_clause": {},
  "maintenance_clause": {},
  "damage_clause": {},
  "regularization_waiver_clause": {},
  "rent_free_clause": {},
  "custom_clause": {},
  "rent_free_start_date": "2024-08-25",
  "rent_free_end_date": "2024-08-25",
  "rent_free_amount": {},
  "tenant_fees_cap_visit_dossier_lease_per_m2": {},
  "tenant_fees_cap_inventory_per_m2": {},
  "landlord_fees_visit_dossier_lease": {},
  "landlord_fees_visit_dossier_lease_description": {},
  "landlord_fees_inventory_entry": {},
  "landlord_fees_inventory_entry_description": {},
  "landlord_fees_other": {},
  "landlord_fees_other_description": {},
  "tenant_fees_visit_dossier_lease": {},
  "tenant_fees_visit_dossier_lease_description": {},
  "tenant_fees_inventory_entry": {},
  "tenant_fees_inventory_entry_description": {},
  "tenant_fees_other": {},
  "tenant_fees_other_description": {},
  "fees_calculation_date": "2024-08-25T15:00:00Z",
  "fees_regulation_compliance": {},
  "fees_agency_name": {},
  "fees_agency_registration_number": {},
  "student_school_name": "Université Paris-Saclay",
  "student_enrollment_year": "2024-2025",
  "student_certificate_provided": {},
  "student_level": "Master 1",
  "mobility_reason": "mission_temporaire",
  "mobility_reason_other": {},
  "initial_duration_months": 6,
  "extended_duration_months": 9,
  "lease_extension_info": {},
  "seasonal_rental_purpose": "vacances",
  "seasonal_purpose_details": {},
  "seasonal_guest_count": 4,
  "seasonal_cleaning_included": {},
  "seasonal_cleaning_fee": 80,
  "seasonal_tourist_tax_included": {},
  "seasonal_tourist_tax_amount": 2.5,
  "seasonal_services_included": "WiFi, household linen, private parking",
  "seasonal_energy_mode": "inclus_forfait",
  "seasonal_cancellation_policy": {},
  "seasonal_declaration_number": "75001-2025-00123",
  "commercial_business_name": "TECH RETAIL SARL",
  "commercial_legal_form": "SARL",
  "commercial_siret": "12345678901234",
  "commercial_rcs": "RCS Paris 987 654 321",
  "commercial_activity": "IT retail and office equipment",
  "commercial_activity_code_ape": "47.11F",
  "commercial_triennial_exit_year_3": "2027-07-01",
  "commercial_triennial_exit_year_6": "2030-07-01",
  "commercial_triennial_exit_year_9": "2033-07-01",
  "commercial_notice_period_months": 6,
  "commercial_ilc_base_value": 130.52,
  "commercial_ilc_base_date": "2024-10-01",
  "commercial_next_revision_date": "2027-01-01",
  "commercial_rent_ceiling_enabled": {},
  "commercial_despecialization_partial": [
    {
      "date": "2025-06-01",
      "activity": "Sale of IT accessories",
      "approved_by": "Jean Dupont"
    }
  ],
  "commercial_despecialization_full": {
    "date": "2026-03-15",
    "old_activity": "IT retail",
    "new_activity": "Restaurant",
    "approved": true,
    "indemnity_amount": 15000
  },
  "commercial_guarantors": [
    {
      "name": "Holding Company XYZ",
      "siret": "98765432109876",
      "address": "10 Avenue des Champs-Élysées, 75008 Paris",
      "guaranteed_amount": 50000,
      "signature_date": "2025-01-01"
    }
  ],
  "commercial_insurance_policy": "POL-RC-2025-789456",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

application/json

Check legal compliance of a lease

GET

https://api.faireplace.com/api

/leases/{lease_id}/compliance

Checks the regulatory compliance of a lease according to applicable legal rules.

Features:

Rent control verification (Alur law) for French leases
Rent regulation verification (high-demand zones)
Verification of regulations specific to the geographic area

For French leases:

Compares the proposed rent with reference rents (reference, increased reference, reduced reference)
Checks if the property is located in a high-demand zone
Provides recommendations in case of non-compliance
Calculates IRL (Rent Reference Index) information in read-only mode

Currently supported rent control zones:

Paris: 75001 to 75020
Lyon: 69001 to 69009, 69100
Plaine Commune: 93200, 93300, 93400, 93450, 93800, 93120, 93430, 93380, 93240
Est Ensemble: 93170, 93000, 93140, 93310, 93260, 93100, 93130, 93500, 93230
Montpellier: 34000, 34070, 34080, 34090
Bordeaux: 33000, 33100, 33200, 33300, 33800
Lille: 59000, 59800, 59160, 59260
Pays Basque: All 64xxx postal codes
Grenoble: All 38xxx postal codes

Note: This method only performs a check without modifying the lease. To check AND automatically update the lease, use POST /leases/{id}/compliance/update.

Check legal compliance of a lease › path Parameters

lease_id

string · uuid · required

Lease ID to check

Example: 550e8400-e29b-41d4-a716-446655440000

Check legal compliance of a lease › Responses

Compliance check completed successfully.

The response contains:

The overall compliance status
A detailed list of each check performed
Recommendations for each detected issue
IRL (Rent Reference Index) information calculated in read-only mode:
- rent_revision_date: Calculated revision date (usually one year after the lease start)
- irl_reference_quarter: IRL reference quarter (format "T{quarter}-{year}", e.g.: "T3-2024")
- irl_reference_value: Current official IRL value

Lease compliance check result

lease_id

string · uuid · required

Lease ID

country_code

string · required

Country code

Example: FR

legislative_zone_name

string · required

Legislative zone name

postal_code

string · required

Postal code

object[] · required

Checks list

required

Compliance status of a check.

Possible values:

"Compliant": The lease complies with regulations
"NonCompliant": The lease does not comply (action required)
"Warning": Warning (compliant but attention required)
"NotApplicable": The check is not applicable to this lease
{"Error": {"message": "..."}}: Error during verification (with detailed message)

Examples:


Code
 
"Compliant"


Code
 
{
  "Error": {
    "message": "Verification error: Unable to retrieve regulation data"
  }
}

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null

IRL reference quarter

irl_reference_value

number | null · decimal

IRL reference value

GET/leases/{lease_id}/compliance

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/compliance

Example Responses

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440000",
  "country_code": "FR",
  "legislative_zone_name": "Île-de-France",
  "postal_code": "75001",
  "compliance_checks": [
    {
      "check_type": "RentControl",
      "status": "Compliant",
      "details": "The rent complies with rent control regulations",
      "recommendations": []
    },
    {
      "check_type": "RentRegulation",
      "status": "Warning",
      "details": "High-demand zone detected for Paris. Special regulations apply.",
      "recommendations": [
        "Comply with rent control rules",
        "Notice period reduced to 1 month in case of termination"
      ]
    }
  ],
  "overall_status": "Warning",
  "rent_revision_date": "2025-01-01",
  "irl_reference_quarter": "T3-2024",
  "irl_reference_value": 142.74
}

Example of a regulation-compliant lease

application/json

List leases for a property

GET

https://api.faireplace.com/api

/leases/estate/{estate_id}

Retrieve all leases associated with a specific property

List leases for a property › path Parameters

estate_id

string · uuid · required

Property ID

List leases for a property › Responses

Lease list retrieved successfully

object[]

Lease list item (simplified version)

id

string · uuid · required

estate_id

string · uuid · required

status

string · enum · required

Lease status

Enum values:

DRAFT

PENDING_SIGNATURE

ACTIVE

NOTICE

FINALISATION

TERMINATED

EXPIRED

Example: ACTIVE

start_date

string · date · required

rent_amount

number · decimal · required

rent_frequency

string · enum · required

Rent payment frequency

Enum values:

MONTHLY

QUARTERLY

ANNUALLY

Example: MONTHLY

reference_number

string | null

end_date

string | null · date

lessee_name

string | null

Formatted name of the primary tenant (PRIMARY role). Format: 'FirstName LastName' for individuals, 'Business Name' for companies. NULL if no tenant.

estate_name

string | null

Name of the associated property. NULL if property deleted.

place_name

string | null

Name or address of the place where the property is located. NULL if not defined.

deposit_amount

number | null · decimal

Security deposit amount

GET/leases/estate/{estate_id}

curl --request GET \
  --url https://api.faireplace.com/api/leases/estate/:estate_id

Example Responses

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "estate_id": "00000000-0000-0000-0000-000000000000",
    "reference_number": {},
    "status": "ACTIVE",
    "start_date": "2024-08-25",
    "end_date": "2024-08-25",
    "rent_amount": 0,
    "rent_frequency": "MONTHLY",
    "lessee_name": {},
    "estate_name": {},
    "place_name": {},
    "deposit_amount": {}
  }
]

application/json

Check and apply legal compliance

POST

https://api.faireplace.com/api

/leases/{lease_id}/compliance/update

Checks the regulatory compliance of a lease AND automatically updates the lease with compliance information.

Difference with GET /compliance:

GET /compliance: Checks only without modifying the lease
POST /compliance/update: Checks AND automatically updates the lease

Automatic updates performed:

For French leases:

Updates is_subject_to_rent_evolution_decree and is_subject_to_reference_rent_cap
Calculates and updates reference_rent_per_m2 and reference_rent_increased_per_m2
Calculates and updates base_rent_amount and rent_complement_amount according to regulations
Updates rent_regulation_zone_type (TENDUE or STANDARD)
Calculates and updates IRL (Rent Reference Index) information:
- rent_revision_date: Rent revision date
- irl_reference_quarter: IRL reference quarter (e.g.: "T3-2024")
- irl_reference_value: Official IRL value
Updates rent_regulation_compliance_status with the overall status
Updates rent_regulation_applied_at and rent_regulation_last_check with the current date

Currently supported rent control zones:

Paris: 75001 to 75020
Lyon: 69001 to 69009, 69100
Plaine Commune: 93200, 93300, 93400, 93450, 93800, 93120, 93430, 93380, 93240
Est Ensemble: 93170, 93000, 93140, 93310, 93260, 93100, 93130, 93500, 93230
Montpellier: 34000, 34070, 34080, 34090
Bordeaux: 33000, 33100, 33200, 33300, 33800
Lille: 59000, 59800, 59160, 59260
Pays Basque: All 64xxx postal codes
Grenoble: All 38xxx postal codes

Important: This operation modifies the lease. Make sure you have LeasesWrite permissions.

Check and apply legal compliance › path Parameters

lease_id

string · uuid · required

Lease ID to check and update

Example: 550e8400-e29b-41d4-a716-446655440000

Check and apply legal compliance › Responses

Compliance checked and lease updated successfully.

The response contains the compliance check result with all calculated information. The lease has been automatically updated in the database with:

Calculated reference rents
IRL information
Compliance status
Regulation metadata

Lease compliance check result

lease_id

string · uuid · required

Lease ID

country_code

string · required

Country code

Example: FR

legislative_zone_name

string · required

Legislative zone name

postal_code

string · required

Postal code

object[] · required

Checks list

required

Compliance status of a check.

Possible values:

"Compliant": The lease complies with regulations
"NonCompliant": The lease does not comply (action required)
"Warning": Warning (compliant but attention required)
"NotApplicable": The check is not applicable to this lease
{"Error": {"message": "..."}}: Error during verification (with detailed message)

Examples:


Code
 
"Compliant"


Code
 
{
  "Error": {
    "message": "Verification error: Unable to retrieve regulation data"
  }
}

rent_revision_date

string | null · date

Rent revision date

irl_reference_quarter

string | null

IRL reference quarter

irl_reference_value

number | null · decimal

IRL reference value

POST/leases/{lease_id}/compliance/update

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/compliance/update

Example Responses

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440000",
  "country_code": "FR",
  "legislative_zone_name": "Île-de-France",
  "postal_code": "75001",
  "compliance_checks": [
    {
      "check_type": "RentControl",
      "status": "Compliant",
      "details": "The rent complies with rent control regulations",
      "recommendations": []
    },
    {
      "check_type": "RentRegulation",
      "status": "Warning",
      "details": "High-demand zone detected for Paris. Special regulations apply.",
      "recommendations": [
        "Comply with rent control rules",
        "Notice period reduced to 1 month in case of termination"
      ]
    }
  ],
  "overall_status": "Warning",
  "rent_revision_date": "2025-01-01",
  "irl_reference_quarter": "T3-2024",
  "irl_reference_value": 142.74
}

Example of successful check and update

application/json

List lease documents

GET

https://api.faireplace.com/api

/leases/{lease_id}/documents

Retrieve all documents associated with a lease

List lease documents › path Parameters

lease_id

string · uuid · required

Lease ID

List lease documents › Responses

Document list retrieved successfully

object[]

Lease document

id

string · uuid · required

Unique identifier of the document

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

document_type

string · maxLength: 100 · required

Document type

Example: CONTRACT

file_path

string · required

File path

Example: /documents/leases/2024/lease-001.pdf

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

description

string | null · maxLength: 500

Document description

Example: Lease contract signed by both parties

GET/leases/{lease_id}/documents

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/documents

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "lease_id": "550e8400-e29b-41d4-a716-446655440001",
    "document_type": "CONTRACT",
    "file_path": "/documents/leases/2024/lease-001.pdf",
    "description": "Lease contract signed by both parties",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

application/json

Add a document to a lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/documents

Add a new document (contract, appendix, etc.) to a lease

Add a document to a lease › path Parameters

lease_id

string · uuid · required

Lease ID

Add a document to a lease › Request Body

Data for uploading a lease document

document_type

string · minLength: 1 · maxLength: 100 · required

Document type

description

string | null · maxLength: 500

Document description

file

string

File to upload

Add a document to a lease › Responses

Document added successfully

Lease document

id

string · uuid · required

Unique identifier of the document

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

document_type

string · maxLength: 100 · required

Document type

Example: CONTRACT

file_path

string · required

File path

Example: /documents/leases/2024/lease-001.pdf

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

description

string | null · maxLength: 500

Document description

Example: Lease contract signed by both parties

POST/leases/{lease_id}/documents

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/documents \
  --header 'Content-Type: multipart/form-data' \
  --form document_type=document_type \
  --form 'description={}' \
  --form file=file

Example Request Body

{
  "document_type": "document_type",
  "description": {},
  "file": "file"
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "document_type": "CONTRACT",
  "file_path": "/documents/leases/2024/lease-001.pdf",
  "description": "Lease contract signed by both parties",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

application/json

Get lease document

GET

https://api.faireplace.com/api

/leases/{lease_id}/documents/{document_id}

Retrieve details of a specific document

Get lease document › path Parameters

lease_id

string · uuid · required

Lease ID

document_id

string · uuid · required

Document ID

Get lease document › Responses

Document retrieved successfully

Lease document

id

string · uuid · required

Unique identifier of the document

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

document_type

string · maxLength: 100 · required

Document type

Example: CONTRACT

file_path

string · required

File path

Example: /documents/leases/2024/lease-001.pdf

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

description

string | null · maxLength: 500

Document description

Example: Lease contract signed by both parties

GET/leases/{lease_id}/documents/{document_id}

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/documents/:document_id

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "document_type": "CONTRACT",
  "file_path": "/documents/leases/2024/lease-001.pdf",
  "description": "Lease contract signed by both parties",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

application/json

Update lease document

PUT

https://api.faireplace.com/api

/leases/{lease_id}/documents/{document_id}

Update the metadata of a lease document

Update lease document › path Parameters

lease_id

string · uuid · required

Lease ID

document_id

string · uuid · required

Document ID

Update lease document › Request Body

Data for updating a lease document

document_type

string | null · minLength: 1 · maxLength: 100

Document type

file_path

string | null · minLength: 1

File path

description

string | null · maxLength: 500

Document description

Update lease document › Responses

Document updated successfully

Lease document

id

string · uuid · required

Unique identifier of the document

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

document_type

string · maxLength: 100 · required

Document type

Example: CONTRACT

file_path

string · required

File path

Example: /documents/leases/2024/lease-001.pdf

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

description

string | null · maxLength: 500

Document description

Example: Lease contract signed by both parties

PUT/leases/{lease_id}/documents/{document_id}

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/documents/:document_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_type": {},
  "file_path": {},
  "description": {}
}
'

Example Request Body

{
  "document_type": {},
  "file_path": {},
  "description": {}
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "document_type": "CONTRACT",
  "file_path": "/documents/leases/2024/lease-001.pdf",
  "description": "Lease contract signed by both parties",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

application/json

Delete a document associated with a lease

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/documents/{document_id}

Delete a document associated with a lease › path Parameters

lease_id

string · uuid · required

Lease ID

document_id

string · uuid · required

Document ID

Delete a document associated with a lease › Responses

Document deleted successfully

No data returned

DELETE/leases/{lease_id}/documents/{document_id}

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/documents/:document_id

Example Responses

No example specified for this content type

List lease amendments

GET

https://api.faireplace.com/api

/leases/{lease_id}/amendments

Retrieve the list of all amendments associated with a lease

List lease amendments › path Parameters

lease_id

string · uuid · required

Lease ID

List lease amendments › Responses

Amendment list retrieved successfully

object[]

Lease amendment

id

string · uuid · required

Unique identifier of the amendment

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

amendment_number

string · maxLength: 100 · required

Amendment number

Example: AVE-001

amendment_type

string · enum · required

Amendment type

Enum values:

RENT_INCREASE

DURATION_EXTENSION

TERMS_MODIFICATION

PARTY_CHANGE

PROPERTY_CHANGE

OTHER

Example: RENT_INCREASE

status

string · enum · required

Amendment status

Enum values:

DRAFT

PENDING_APPROVAL

APPROVED

REJECTED

ACTIVE

EXPIRED

Example: DRAFT

effective_date

string · date · required

Effective date of the amendment

Example: 2024-06-01

description

string · required

Description of the amendment

Example: Rent increase following IRL revision

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

created_by

string · uuid · required

ID of the creator user

updated_by

string · uuid · required

ID of the last modifier user

signature_date

string | null · date

Amendment signature date

Example: 2024-05-15

validation_status

string | null · maxLength: 100

Validation status (VARCHAR in DB)

validation_date

string | null · date-time

Validation date

validated_by

string | null · uuid

ID of the user who validated

legal_reference

string | null · maxLength: 200

Legal reference

special_conditions

string | null · maxLength: 2000

Special conditions of the amendment

notes

string | null · maxLength: 1000

Internal notes

GET/leases/{lease_id}/amendments

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/amendments

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "lease_id": "550e8400-e29b-41d4-a716-446655440001",
    "amendment_number": "AVE-001",
    "amendment_type": "RENT_INCREASE",
    "status": "DRAFT",
    "effective_date": "2024-06-01",
    "signature_date": "2024-05-15",
    "validation_status": {},
    "validation_date": "2024-08-25T15:00:00Z",
    "validated_by": "00000000-0000-0000-0000-000000000000",
    "legal_reference": {},
    "description": "Rent increase following IRL revision",
    "special_conditions": {},
    "notes": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "created_by": "00000000-0000-0000-0000-000000000000",
    "updated_by": "00000000-0000-0000-0000-000000000000"
  }
]

application/json

Create a lease amendment

POST

https://api.faireplace.com/api

/leases/{lease_id}/amendments

Create a new amendment to modify the terms of a lease

Create a lease amendment › path Parameters

lease_id

string · uuid · required

Lease ID

Create a lease amendment › Request Body

Data for creating a new lease amendment

amendment_number

string · minLength: 1 · maxLength: 100 · required

Amendment number

amendment_type

string · enum · required

Amendment type

Enum values:

RENT_INCREASE

DURATION_EXTENSION

TERMS_MODIFICATION

PARTY_CHANGE

PROPERTY_CHANGE

OTHER

Example: RENT_INCREASE

effective_date

string · date · required

Effective date of the amendment

description

string · required

Description of the amendment

created_by

string · uuid · required

ID of the creator user (required)

signature_date

string | null · date

Signature date

legal_reference

string | null · maxLength: 200

Legal reference

special_conditions

string | null · maxLength: 2000

Special conditions

notes

string | null · maxLength: 1000

Internal notes

Create a lease amendment › Responses

Amendment created successfully

Lease amendment

id

string · uuid · required

Unique identifier of the amendment

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

amendment_number

string · maxLength: 100 · required

Amendment number

Example: AVE-001

amendment_type

string · enum · required

Amendment type

Enum values:

RENT_INCREASE

DURATION_EXTENSION

TERMS_MODIFICATION

PARTY_CHANGE

PROPERTY_CHANGE

OTHER

Example: RENT_INCREASE

status

string · enum · required

Amendment status

Enum values:

DRAFT

PENDING_APPROVAL

APPROVED

REJECTED

ACTIVE

EXPIRED

Example: DRAFT

effective_date

string · date · required

Effective date of the amendment

Example: 2024-06-01

description

string · required

Description of the amendment

Example: Rent increase following IRL revision

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

created_by

string · uuid · required

ID of the creator user

updated_by

string · uuid · required

ID of the last modifier user

signature_date

string | null · date

Amendment signature date

Example: 2024-05-15

validation_status

string | null · maxLength: 100

Validation status (VARCHAR in DB)

validation_date

string | null · date-time

Validation date

validated_by

string | null · uuid

ID of the user who validated

legal_reference

string | null · maxLength: 200

Legal reference

special_conditions

string | null · maxLength: 2000

Special conditions of the amendment

notes

string | null · maxLength: 1000

Internal notes

POST/leases/{lease_id}/amendments

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/amendments \
  --header 'Content-Type: application/json' \
  --data '
{
  "amendment_number": "amendment_number",
  "amendment_type": "RENT_INCREASE",
  "effective_date": "2024-08-25",
  "signature_date": "2024-08-25",
  "legal_reference": {},
  "description": "description",
  "special_conditions": {},
  "notes": {},
  "created_by": "00000000-0000-0000-0000-000000000000"
}
'

Example Request Body

{
  "amendment_number": "amendment_number",
  "amendment_type": "RENT_INCREASE",
  "effective_date": "2024-08-25",
  "signature_date": "2024-08-25",
  "legal_reference": {},
  "description": "description",
  "special_conditions": {},
  "notes": {},
  "created_by": "00000000-0000-0000-0000-000000000000"
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "amendment_number": "AVE-001",
  "amendment_type": "RENT_INCREASE",
  "status": "DRAFT",
  "effective_date": "2024-06-01",
  "signature_date": "2024-05-15",
  "validation_status": {},
  "validation_date": "2024-08-25T15:00:00Z",
  "validated_by": "00000000-0000-0000-0000-000000000000",
  "legal_reference": {},
  "description": "Rent increase following IRL revision",
  "special_conditions": {},
  "notes": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by": "00000000-0000-0000-0000-000000000000",
  "updated_by": "00000000-0000-0000-0000-000000000000"
}

application/json

Get a lease amendment

GET

https://api.faireplace.com/api

/leases/{lease_id}/amendments/{amendment_id}

Retrieve the details of a specific amendment

Get a lease amendment › path Parameters

lease_id

string · uuid · required

Lease ID

amendment_id

string · uuid · required

Amendment ID

Get a lease amendment › Responses

Amendment retrieved successfully

Lease amendment

id

string · uuid · required

Unique identifier of the amendment

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

amendment_number

string · maxLength: 100 · required

Amendment number

Example: AVE-001

amendment_type

string · enum · required

Amendment type

Enum values:

RENT_INCREASE

DURATION_EXTENSION

TERMS_MODIFICATION

PARTY_CHANGE

PROPERTY_CHANGE

OTHER

Example: RENT_INCREASE

status

string · enum · required

Amendment status

Enum values:

DRAFT

PENDING_APPROVAL

APPROVED

REJECTED

ACTIVE

EXPIRED

Example: DRAFT

effective_date

string · date · required

Effective date of the amendment

Example: 2024-06-01

description

string · required

Description of the amendment

Example: Rent increase following IRL revision

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

created_by

string · uuid · required

ID of the creator user

updated_by

string · uuid · required

ID of the last modifier user

signature_date

string | null · date

Amendment signature date

Example: 2024-05-15

validation_status

string | null · maxLength: 100

Validation status (VARCHAR in DB)

validation_date

string | null · date-time

Validation date

validated_by

string | null · uuid

ID of the user who validated

legal_reference

string | null · maxLength: 200

Legal reference

special_conditions

string | null · maxLength: 2000

Special conditions of the amendment

notes

string | null · maxLength: 1000

Internal notes

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

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/amendments/:amendment_id

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "amendment_number": "AVE-001",
  "amendment_type": "RENT_INCREASE",
  "status": "DRAFT",
  "effective_date": "2024-06-01",
  "signature_date": "2024-05-15",
  "validation_status": {},
  "validation_date": "2024-08-25T15:00:00Z",
  "validated_by": "00000000-0000-0000-0000-000000000000",
  "legal_reference": {},
  "description": "Rent increase following IRL revision",
  "special_conditions": {},
  "notes": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by": "00000000-0000-0000-0000-000000000000",
  "updated_by": "00000000-0000-0000-0000-000000000000"
}

application/json

Update a lease amendment

PUT

https://api.faireplace.com/api

/leases/{lease_id}/amendments/{amendment_id}

Update the information of an existing amendment

Update a lease amendment › path Parameters

lease_id

string · uuid · required

Lease ID

amendment_id

string · uuid · required

Amendment ID

Update a lease amendment › Request Body

Data for updating a lease amendment

amendment_type

string · enum

Amendment type

Enum values:

RENT_INCREASE

DURATION_EXTENSION

TERMS_MODIFICATION

PARTY_CHANGE

PROPERTY_CHANGE

OTHER

Example: RENT_INCREASE

status

string · enum

Amendment status

Enum values:

DRAFT

PENDING_APPROVAL

APPROVED

REJECTED

ACTIVE

EXPIRED

Example: DRAFT

effective_date

string | null · date

Effective date

signature_date

string | null · date

Signature date

validation_status

string | null · maxLength: 100

Validation status (VARCHAR)

validation_date

string | null · date-time

Validation date

validated_by

string | null · uuid

Validator ID

legal_reference

string | null · maxLength: 200

Legal reference

description

string | null

Description

special_conditions

string | null · maxLength: 2000

Special conditions

notes

string | null · maxLength: 1000

Internal notes

updated_by

string | null · uuid

Modifier ID

Update a lease amendment › Responses

Amendment updated successfully

Lease amendment

id

string · uuid · required

Unique identifier of the amendment

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

amendment_number

string · maxLength: 100 · required

Amendment number

Example: AVE-001

amendment_type

string · enum · required

Amendment type

Enum values:

RENT_INCREASE

DURATION_EXTENSION

TERMS_MODIFICATION

PARTY_CHANGE

PROPERTY_CHANGE

OTHER

Example: RENT_INCREASE

status

string · enum · required

Amendment status

Enum values:

DRAFT

PENDING_APPROVAL

APPROVED

REJECTED

ACTIVE

EXPIRED

Example: DRAFT

effective_date

string · date · required

Effective date of the amendment

Example: 2024-06-01

description

string · required

Description of the amendment

Example: Rent increase following IRL revision

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

created_by

string · uuid · required

ID of the creator user

updated_by

string · uuid · required

ID of the last modifier user

signature_date

string | null · date

Amendment signature date

Example: 2024-05-15

validation_status

string | null · maxLength: 100

Validation status (VARCHAR in DB)

validation_date

string | null · date-time

Validation date

validated_by

string | null · uuid

ID of the user who validated

legal_reference

string | null · maxLength: 200

Legal reference

special_conditions

string | null · maxLength: 2000

Special conditions of the amendment

notes

string | null · maxLength: 1000

Internal notes

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

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/amendments/:amendment_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "amendment_type": "RENT_INCREASE",
  "status": "DRAFT",
  "effective_date": "2024-08-25",
  "signature_date": "2024-08-25",
  "validation_status": {},
  "validation_date": "2024-08-25T15:00:00Z",
  "validated_by": "00000000-0000-0000-0000-000000000000",
  "legal_reference": {},
  "description": {},
  "special_conditions": {},
  "notes": {},
  "updated_by": "00000000-0000-0000-0000-000000000000"
}
'

Example Request Body

{
  "amendment_type": "RENT_INCREASE",
  "status": "DRAFT",
  "effective_date": "2024-08-25",
  "signature_date": "2024-08-25",
  "validation_status": {},
  "validation_date": "2024-08-25T15:00:00Z",
  "validated_by": "00000000-0000-0000-0000-000000000000",
  "legal_reference": {},
  "description": {},
  "special_conditions": {},
  "notes": {},
  "updated_by": "00000000-0000-0000-0000-000000000000"
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "amendment_number": "AVE-001",
  "amendment_type": "RENT_INCREASE",
  "status": "DRAFT",
  "effective_date": "2024-06-01",
  "signature_date": "2024-05-15",
  "validation_status": {},
  "validation_date": "2024-08-25T15:00:00Z",
  "validated_by": "00000000-0000-0000-0000-000000000000",
  "legal_reference": {},
  "description": "Rent increase following IRL revision",
  "special_conditions": {},
  "notes": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by": "00000000-0000-0000-0000-000000000000",
  "updated_by": "00000000-0000-0000-0000-000000000000"
}

application/json

Delete a lease amendment

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/amendments/{amendment_id}

Delete an amendment associated with a lease

Delete a lease amendment › path Parameters

lease_id

string · uuid · required

Lease ID

amendment_id

string · uuid · required

Amendment ID

Delete a lease amendment › Responses

Amendment deleted successfully

No data returned

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

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/amendments/:amendment_id

Example Responses

No example specified for this content type

Change amendment status

PUT

https://api.faireplace.com/api

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

Change the status of an amendment (DRAFT, PENDING_SIGNATURE, ACTIVE, CANCELLED, REJECTED)

Change amendment status › path Parameters

lease_id

string · uuid · required

Lease ID

amendment_id

string · uuid · required

Amendment ID

Change amendment status › Request Body

Data for changing the status of an amendment

status

string · enum · required

Amendment status

Enum values:

DRAFT

PENDING_APPROVAL

APPROVED

REJECTED

ACTIVE

EXPIRED

Example: DRAFT

reason

string | null · maxLength: 500

Reason for the status change

Change amendment status › Responses

Amendment status updated successfully

Lease amendment

id

string · uuid · required

Unique identifier of the amendment

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

amendment_number

string · maxLength: 100 · required

Amendment number

Example: AVE-001

amendment_type

string · enum · required

Amendment type

Enum values:

RENT_INCREASE

DURATION_EXTENSION

TERMS_MODIFICATION

PARTY_CHANGE

PROPERTY_CHANGE

OTHER

Example: RENT_INCREASE

status

string · enum · required

Amendment status

Enum values:

DRAFT

PENDING_APPROVAL

APPROVED

REJECTED

ACTIVE

EXPIRED

Example: DRAFT

effective_date

string · date · required

Effective date of the amendment

Example: 2024-06-01

description

string · required

Description of the amendment

Example: Rent increase following IRL revision

created_at

string · date-time · required

Creation date

Example: 2024-01-15T10:30:00Z

updated_at

string · date-time · required

Last modification date

Example: 2024-01-15T10:30:00Z

created_by

string · uuid · required

ID of the creator user

updated_by

string · uuid · required

ID of the last modifier user

signature_date

string | null · date

Amendment signature date

Example: 2024-05-15

validation_status

string | null · maxLength: 100

Validation status (VARCHAR in DB)

validation_date

string | null · date-time

Validation date

validated_by

string | null · uuid

ID of the user who validated

legal_reference

string | null · maxLength: 200

Legal reference

special_conditions

string | null · maxLength: 2000

Special conditions of the amendment

notes

string | null · maxLength: 1000

Internal notes

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

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/amendments/:amendment_id/status \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "DRAFT",
  "reason": {}
}
'

Example Request Body

{
  "status": "DRAFT",
  "reason": {}
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "amendment_number": "AVE-001",
  "amendment_type": "RENT_INCREASE",
  "status": "DRAFT",
  "effective_date": "2024-06-01",
  "signature_date": "2024-05-15",
  "validation_status": {},
  "validation_date": "2024-08-25T15:00:00Z",
  "validated_by": "00000000-0000-0000-0000-000000000000",
  "legal_reference": {},
  "description": "Rent increase following IRL revision",
  "special_conditions": {},
  "notes": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by": "00000000-0000-0000-0000-000000000000",
  "updated_by": "00000000-0000-0000-0000-000000000000"
}

application/json

List charges of a lease

GET

https://api.faireplace.com/api

/leases/{lease_id}/charges

Retrieve the list of all charges associated with a lease

List charges of a lease › path Parameters

lease_id

string · uuid · required

Lease ID

List charges of a lease › Responses

List of charges retrieved successfully

object[]

Rental charge

id

string · uuid · required

Unique identifier of the charge

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

calculation_method

string · enum · required

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
FORFAIT requires FORFAIT as calculation basis
DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
PROVISION can be used with all calculation bases
The mode must be allowed for the lease type (allow_provisional, allow_fixed)

Enum values:

FORFAIT

PROVISION

DEPENSE_REELLE

RELEVE_DIRECT

Example: PROVISION

calculation_basis

string · enum · required

Charge calculation basis (specific business rules only).

Compatibility rules:

FORFAIT requires FORFAIT as billing mode
DEPENSE_REELLE requires DEPENSE_REELLE as billing mode or can be used with PROVISION
PERSONNEL_75_POURCENT, PERSONNEL_40_POURCENT, PERSONNEL_100_POURCENT:
- Require the EMPLOYEE category
- Can be used with DEPENSE_REELLE or PROVISION as billing mode

Enum values:

DEPENSE_REELLE

FORFAIT

PERSONNEL_75_POURCENT

PERSONNEL_40_POURCENT

PERSONNEL_100_POURCENT

Example: FORFAIT

amount

number · decimal · min: 0 · required

Charge amount

Example: 150

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

service_place_id

string | null · uuid

Place service ID

category_id

string | null · uuid

Charge category ID

billing_period_start

string | null · date

Billing period start date

billing_period_end

string | null · date

Billing period end date

last_regularization_date

string | null · date

Last regularization date

distribution_key_id

string | null · uuid

Distribution key ID

notes

string | null · maxLength: 1000

Notes about the charge

object

Contribution for sharing energy savings (Energy Transition Act)

object

Insurance taken out by the landlord on behalf of co-tenants

GET/leases/{lease_id}/charges

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/charges

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "lease_id": "550e8400-e29b-41d4-a716-446655440001",
    "service_place_id": "00000000-0000-0000-0000-000000000000",
    "category_id": "00000000-0000-0000-0000-000000000000",
    "calculation_method": "PROVISION",
    "calculation_basis": "FORFAIT",
    "amount": 150,
    "billing_period_start": "2024-08-25",
    "billing_period_end": "2024-08-25",
    "last_regularization_date": "2024-08-25",
    "distribution_key_id": "00000000-0000-0000-0000-000000000000",
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z",
    "energy_efficiency": {
      "id": "00000000-0000-0000-0000-000000000000",
      "lease_charge_id": "00000000-0000-0000-0000-000000000000",
      "baseline_consumption": 0,
      "target_savings_percentage": 0,
      "monthly_contribution_amount": 0,
      "remaining_months": 0,
      "work_description": "work_description",
      "work_cost": {},
      "energy_audit_reference": {},
      "start_date": "2024-08-25",
      "end_date": "2024-08-25",
      "notes": {},
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    },
    "insurance": {
      "id": "00000000-0000-0000-0000-000000000000",
      "lease_charge_id": "00000000-0000-0000-0000-000000000000",
      "contract_number": "contract_number",
      "insurance_company": "insurance_company",
      "annual_premium": 0,
      "recoverable_amount": 0,
      "coverage_details": "coverage_details",
      "policy_start_date": "2024-08-25",
      "policy_end_date": "2024-08-25",
      "deductible_amount": {},
      "coverage_limits": {},
      "exclusions": {},
      "notes": {},
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  }
]

application/json

Create a lease charge

POST

https://api.faireplace.com/api

/leases/{lease_id}/charges

Create a new lease charge for a lease.

Validations performed:

service_place / lease compatibility: The service must be attached to the same place as the lease's estate
Automatic resolution of the distribution key: If distribution_key_id is not provided, uses default_distribution_key_id from the service_place
Distribution / billing consistency: Checks that the distribution is compatible with the billing method (e.g., CONSOMMATION_MESUREE requires RELEVE_DIRECT or PROVISION)
Method / basis consistency: Checks that the billing method is compatible with the calculation basis
Lease type compatibility: Checks that the category and billing method are allowed for this lease type
Period validation: Checks that billing periods are within the lease boundaries and respect max_provisional_months if applicable
Category x basis compatibility: Checks that personnel calculation bases are only used with the EMPLOYEE category

Create a lease charge › path Parameters

lease_id

string · uuid · required

Lease ID

Create a lease charge › Request Body

Data for creating a rental charge. **Validation rules:** - If `service_place_id` is provided, the service must be attached to the same place as the lease's estate and must be chargeable - If `distribution_key_id` is not provided, it will be automatically resolved from `service_place.default_distribution_key_id` (required if `service_place_id` is provided) - The distribution key allocation must be compatible with `calculation_method` (e.g.: `CONSOMMATION_MESUREE` requires `RELEVE_DIRECT` or `PROVISION`) - `calculation_method` and `calculation_basis` must be compatible (e.g.: `FORFAIT` requires `FORFAIT` as basis) - The category (via `category_id` or `service_place.category_id`) must be allowed for the lease type - If `calculation_method` is `PROVISION`, the period duration must not exceed `max_provisional_months` of the lease type - Billing periods must be within the lease boundaries (between `lease.start_date` and `lease.end_date`) - If `category_id` corresponds to `EMPLOYEE`, `calculation_basis` must be `PERSONNEL_75_POURCENT`, `PERSONNEL_40_POURCENT` or `PERSONNEL_100_POURCENT`

calculation_method

string · enum · required

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
FORFAIT requires FORFAIT as calculation basis
DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
PROVISION can be used with all calculation bases
The mode must be allowed for the lease type (allow_provisional, allow_fixed)

Enum values:

FORFAIT

PROVISION

DEPENSE_REELLE

RELEVE_DIRECT

Example: PROVISION

calculation_basis

string · enum · required

Charge calculation basis (specific business rules only).

Compatibility rules:

FORFAIT requires FORFAIT as billing mode
DEPENSE_REELLE requires DEPENSE_REELLE as billing mode or can be used with PROVISION
PERSONNEL_75_POURCENT, PERSONNEL_40_POURCENT, PERSONNEL_100_POURCENT:
- Require the EMPLOYEE category
- Can be used with DEPENSE_REELLE or PROVISION as billing mode

Enum values:

DEPENSE_REELLE

FORFAIT

PERSONNEL_75_POURCENT

PERSONNEL_40_POURCENT

PERSONNEL_100_POURCENT

Example: FORFAIT

amount

number · decimal · min: 0 · required

Charge amount

service_place_id

string | null · uuid

Place service ID. If provided:

The service must be attached to the same place as the lease's estate
The service must be chargeable (is_chargeable = true)
The service must have a default_distribution_key_id if distribution_key_id is not provided

category_id

string | null · uuid

Category ID. If not provided, it will be resolved from service_place.category_id if service_place_id is provided. The category must be allowed for the lease type.

billing_period_start

string | null · date

Billing period start date. Must be:

= lease.start_date
<= billing_period_end if provided
<= lease.end_date if the lease has an end date

billing_period_end

string | null · date

Billing period end date. Must be:

= billing_period_start
<= lease.end_date if the lease has an end date
If calculation_method is PROVISION, the duration must not exceed max_provisional_months of the lease type

distribution_key_id

string | null · uuid

Distribution key ID. If not provided:

Will be resolved from service_place.default_distribution_key_id if service_place_id is provided
Otherwise, an error will be returned

notes

string | null · maxLength: 1000

Notes

object

Data for creating a new energy efficiency contribution when creating a charge

object

Data for creating a new co-tenancy insurance when creating a charge

Create a lease charge › Responses

Charge created successfully

Rental charge

id

string · uuid · required

Unique identifier of the charge

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

calculation_method

string · enum · required

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
FORFAIT requires FORFAIT as calculation basis
DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
PROVISION can be used with all calculation bases
The mode must be allowed for the lease type (allow_provisional, allow_fixed)

Enum values:

FORFAIT

PROVISION

DEPENSE_REELLE

RELEVE_DIRECT

Example: PROVISION

calculation_basis

string · enum · required

Charge calculation basis (specific business rules only).

Compatibility rules:

FORFAIT requires FORFAIT as billing mode
DEPENSE_REELLE requires DEPENSE_REELLE as billing mode or can be used with PROVISION
PERSONNEL_75_POURCENT, PERSONNEL_40_POURCENT, PERSONNEL_100_POURCENT:
- Require the EMPLOYEE category
- Can be used with DEPENSE_REELLE or PROVISION as billing mode

Enum values:

DEPENSE_REELLE

FORFAIT

PERSONNEL_75_POURCENT

PERSONNEL_40_POURCENT

PERSONNEL_100_POURCENT

Example: FORFAIT

amount

number · decimal · min: 0 · required

Charge amount

Example: 150

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

service_place_id

string | null · uuid

Place service ID

category_id

string | null · uuid

Charge category ID

billing_period_start

string | null · date

Billing period start date

billing_period_end

string | null · date

Billing period end date

last_regularization_date

string | null · date

Last regularization date

distribution_key_id

string | null · uuid

Distribution key ID

notes

string | null · maxLength: 1000

Notes about the charge

object

Contribution for sharing energy savings (Energy Transition Act)

object

Insurance taken out by the landlord on behalf of co-tenants

POST/leases/{lease_id}/charges

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/charges \
  --header 'Content-Type: application/json' \
  --data '
{
  "service_place_id": "00000000-0000-0000-0000-000000000000",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": 0,
  "billing_period_start": "2024-08-25",
  "billing_period_end": "2024-08-25",
  "distribution_key_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "energy_efficiency": {
    "baseline_consumption": 15000,
    "target_savings_percentage": 25,
    "monthly_contribution_amount": 50,
    "duration_months": 36,
    "work_description": "Attic thermal insulation and boiler replacement",
    "work_cost": 18000,
    "energy_audit_reference": "DPE-2024-001234",
    "start_date": "2024-01-01",
    "notes": {}
  },
  "insurance": {
    "contract_number": "ASS-COL-2024-001",
    "insurance_company": "AXA Assurances",
    "annual_premium": 1200,
    "recoverable_amount": 1200,
    "coverage_details": "Civil liability, water damage, fire",
    "policy_start_date": "2024-01-01",
    "policy_end_date": "2024-12-31",
    "deductible_amount": 150,
    "coverage_limits": {
      "civil_liability": 2000000,
      "water_damage": 50000
    },
    "exclusions": "Intentional damage, undeclared natural disasters",
    "notes": {}
  }
}
'

Example Request Body

{
  "service_place_id": "00000000-0000-0000-0000-000000000000",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": 0,
  "billing_period_start": "2024-08-25",
  "billing_period_end": "2024-08-25",
  "distribution_key_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "energy_efficiency": {
    "baseline_consumption": 15000,
    "target_savings_percentage": 25,
    "monthly_contribution_amount": 50,
    "duration_months": 36,
    "work_description": "Attic thermal insulation and boiler replacement",
    "work_cost": 18000,
    "energy_audit_reference": "DPE-2024-001234",
    "start_date": "2024-01-01",
    "notes": {}
  },
  "insurance": {
    "contract_number": "ASS-COL-2024-001",
    "insurance_company": "AXA Assurances",
    "annual_premium": 1200,
    "recoverable_amount": 1200,
    "coverage_details": "Civil liability, water damage, fire",
    "policy_start_date": "2024-01-01",
    "policy_end_date": "2024-12-31",
    "deductible_amount": 150,
    "coverage_limits": {
      "civil_liability": 2000000,
      "water_damage": 50000
    },
    "exclusions": "Intentional damage, undeclared natural disasters",
    "notes": {}
  }
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "service_place_id": "00000000-0000-0000-0000-000000000000",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": 150,
  "billing_period_start": "2024-08-25",
  "billing_period_end": "2024-08-25",
  "last_regularization_date": "2024-08-25",
  "distribution_key_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z",
  "energy_efficiency": {
    "id": "00000000-0000-0000-0000-000000000000",
    "lease_charge_id": "00000000-0000-0000-0000-000000000000",
    "baseline_consumption": 0,
    "target_savings_percentage": 0,
    "monthly_contribution_amount": 0,
    "remaining_months": 0,
    "work_description": "work_description",
    "work_cost": {},
    "energy_audit_reference": {},
    "start_date": "2024-08-25",
    "end_date": "2024-08-25",
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  },
  "insurance": {
    "id": "00000000-0000-0000-0000-000000000000",
    "lease_charge_id": "00000000-0000-0000-0000-000000000000",
    "contract_number": "contract_number",
    "insurance_company": "insurance_company",
    "annual_premium": 0,
    "recoverable_amount": 0,
    "coverage_details": "coverage_details",
    "policy_start_date": "2024-08-25",
    "policy_end_date": "2024-08-25",
    "deductible_amount": {},
    "coverage_limits": {},
    "exclusions": {},
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

application/json

Get lease charge

GET

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}

Retrieve details of a specific charge

Get lease charge › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Get lease charge › Responses

Charge retrieved successfully

Rental charge

id

string · uuid · required

Unique identifier of the charge

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

calculation_method

string · enum · required

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
FORFAIT requires FORFAIT as calculation basis
DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
PROVISION can be used with all calculation bases
The mode must be allowed for the lease type (allow_provisional, allow_fixed)

Enum values:

FORFAIT

PROVISION

DEPENSE_REELLE

RELEVE_DIRECT

Example: PROVISION

calculation_basis

string · enum · required

Charge calculation basis (specific business rules only).

Compatibility rules:

FORFAIT requires FORFAIT as billing mode
DEPENSE_REELLE requires DEPENSE_REELLE as billing mode or can be used with PROVISION
PERSONNEL_75_POURCENT, PERSONNEL_40_POURCENT, PERSONNEL_100_POURCENT:
- Require the EMPLOYEE category
- Can be used with DEPENSE_REELLE or PROVISION as billing mode

Enum values:

DEPENSE_REELLE

FORFAIT

PERSONNEL_75_POURCENT

PERSONNEL_40_POURCENT

PERSONNEL_100_POURCENT

Example: FORFAIT

amount

number · decimal · min: 0 · required

Charge amount

Example: 150

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

service_place_id

string | null · uuid

Place service ID

category_id

string | null · uuid

Charge category ID

billing_period_start

string | null · date

Billing period start date

billing_period_end

string | null · date

Billing period end date

last_regularization_date

string | null · date

Last regularization date

distribution_key_id

string | null · uuid

Distribution key ID

notes

string | null · maxLength: 1000

Notes about the charge

object

Contribution for sharing energy savings (Energy Transition Act)

object

Insurance taken out by the landlord on behalf of co-tenants

GET/leases/{lease_id}/charges/{charge_id}

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "service_place_id": "00000000-0000-0000-0000-000000000000",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": 150,
  "billing_period_start": "2024-08-25",
  "billing_period_end": "2024-08-25",
  "last_regularization_date": "2024-08-25",
  "distribution_key_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z",
  "energy_efficiency": {
    "id": "00000000-0000-0000-0000-000000000000",
    "lease_charge_id": "00000000-0000-0000-0000-000000000000",
    "baseline_consumption": 0,
    "target_savings_percentage": 0,
    "monthly_contribution_amount": 0,
    "remaining_months": 0,
    "work_description": "work_description",
    "work_cost": {},
    "energy_audit_reference": {},
    "start_date": "2024-08-25",
    "end_date": "2024-08-25",
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  },
  "insurance": {
    "id": "00000000-0000-0000-0000-000000000000",
    "lease_charge_id": "00000000-0000-0000-0000-000000000000",
    "contract_number": "contract_number",
    "insurance_company": "insurance_company",
    "annual_premium": 0,
    "recoverable_amount": 0,
    "coverage_details": "coverage_details",
    "policy_start_date": "2024-08-25",
    "policy_end_date": "2024-08-25",
    "deductible_amount": {},
    "coverage_limits": {},
    "exclusions": {},
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

application/json

Update lease charge

PUT

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}

Update the information of an existing charge.

Validations performed:

service_place / lease compatibility: The service must be attached to the same place as the lease's estate
Automatic resolution of the distribution key: If distribution_key_id is not provided, uses default_distribution_key_id from the service_place or the existing value
Distribution / billing consistency: Checks that the distribution is compatible with the billing method
Method / basis consistency: Checks that the billing method is compatible with the calculation basis
Lease type compatibility: Checks that the category and billing method are allowed for this lease type
Period validation: Checks that billing periods are within the lease boundaries and respect max_provisional_months if applicable
Category x basis compatibility: Checks that personnel calculation bases are only used with the EMPLOYEE category

Update lease charge › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Update lease charge › Request Body

Data for updating a rental charge. **Validation rules:** - The same validations as for creation apply to modified fields - Values not provided retain their existing values - If `service_place_id` is modified, service_place / lease compatibility validations apply - If `calculation_method` or `calculation_basis` are modified, consistency validations apply

service_place_id

string | null · uuid

Service ID. If modified, the service must be attached to the same place as the lease's estate and must be chargeable

category_id

string | null · uuid

Category ID. If modified, the category must be allowed for the lease type

calculation_method

string · enum

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
FORFAIT requires FORFAIT as calculation basis
DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
PROVISION can be used with all calculation bases
The mode must be allowed for the lease type (allow_provisional, allow_fixed)

Enum values:

FORFAIT

PROVISION

DEPENSE_REELLE

RELEVE_DIRECT

Example: PROVISION

calculation_basis

string · enum

Charge calculation basis (specific business rules only).

Compatibility rules:

FORFAIT requires FORFAIT as billing mode
DEPENSE_REELLE requires DEPENSE_REELLE as billing mode or can be used with PROVISION
PERSONNEL_75_POURCENT, PERSONNEL_40_POURCENT, PERSONNEL_100_POURCENT:
- Require the EMPLOYEE category
- Can be used with DEPENSE_REELLE or PROVISION as billing mode

Enum values:

DEPENSE_REELLE

FORFAIT

PERSONNEL_75_POURCENT

PERSONNEL_40_POURCENT

PERSONNEL_100_POURCENT

Example: FORFAIT

amount

number | null · decimal · min: 0

billing_period_start

string | null · date

Billing period start date. If modified, must respect the lease boundaries

billing_period_end

string | null · date

Billing period end date. If modified, must respect the lease boundaries and max_provisional_months if applicable

last_regularization_date

string | null · date

Last regularization date

distribution_key_id

string | null · uuid

Distribution key ID. If modified, must be compatible with calculation_method

notes

string | null · maxLength: 1000

object

Data for updating an energy efficiency contribution

object

Data for updating a co-tenancy insurance

Update lease charge › Responses

Charge updated successfully

Rental charge

id

string · uuid · required

Unique identifier of the charge

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

calculation_method

string · enum · required

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
FORFAIT requires FORFAIT as calculation basis
DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
PROVISION can be used with all calculation bases
The mode must be allowed for the lease type (allow_provisional, allow_fixed)

Enum values:

FORFAIT

PROVISION

DEPENSE_REELLE

RELEVE_DIRECT

Example: PROVISION

calculation_basis

string · enum · required

Charge calculation basis (specific business rules only).

Compatibility rules:

FORFAIT requires FORFAIT as billing mode
DEPENSE_REELLE requires DEPENSE_REELLE as billing mode or can be used with PROVISION
PERSONNEL_75_POURCENT, PERSONNEL_40_POURCENT, PERSONNEL_100_POURCENT:
- Require the EMPLOYEE category
- Can be used with DEPENSE_REELLE or PROVISION as billing mode

Enum values:

DEPENSE_REELLE

FORFAIT

PERSONNEL_75_POURCENT

PERSONNEL_40_POURCENT

PERSONNEL_100_POURCENT

Example: FORFAIT

amount

number · decimal · min: 0 · required

Charge amount

Example: 150

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

service_place_id

string | null · uuid

Place service ID

category_id

string | null · uuid

Charge category ID

billing_period_start

string | null · date

Billing period start date

billing_period_end

string | null · date

Billing period end date

last_regularization_date

string | null · date

Last regularization date

distribution_key_id

string | null · uuid

Distribution key ID

notes

string | null · maxLength: 1000

Notes about the charge

object

Contribution for sharing energy savings (Energy Transition Act)

object

Insurance taken out by the landlord on behalf of co-tenants

PUT/leases/{lease_id}/charges/{charge_id}

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "service_place_id": "00000000-0000-0000-0000-000000000000",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": {},
  "billing_period_start": "2024-08-25",
  "billing_period_end": "2024-08-25",
  "last_regularization_date": "2024-08-25",
  "distribution_key_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "energy_efficiency": {
    "baseline_consumption": {},
    "target_savings_percentage": {},
    "monthly_contribution_amount": {},
    "remaining_months": {},
    "work_description": {},
    "work_cost": {},
    "energy_audit_reference": {},
    "start_date": "2024-08-25",
    "end_date": "2024-08-25",
    "notes": {}
  },
  "insurance": {
    "contract_number": {},
    "insurance_company": {},
    "annual_premium": {},
    "recoverable_amount": {},
    "coverage_details": {},
    "policy_start_date": "2024-08-25",
    "policy_end_date": "2024-08-25",
    "deductible_amount": {},
    "coverage_limits": {},
    "exclusions": {},
    "notes": {}
  }
}
'

Example Request Body

{
  "service_place_id": "00000000-0000-0000-0000-000000000000",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": {},
  "billing_period_start": "2024-08-25",
  "billing_period_end": "2024-08-25",
  "last_regularization_date": "2024-08-25",
  "distribution_key_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "energy_efficiency": {
    "baseline_consumption": {},
    "target_savings_percentage": {},
    "monthly_contribution_amount": {},
    "remaining_months": {},
    "work_description": {},
    "work_cost": {},
    "energy_audit_reference": {},
    "start_date": "2024-08-25",
    "end_date": "2024-08-25",
    "notes": {}
  },
  "insurance": {
    "contract_number": {},
    "insurance_company": {},
    "annual_premium": {},
    "recoverable_amount": {},
    "coverage_details": {},
    "policy_start_date": "2024-08-25",
    "policy_end_date": "2024-08-25",
    "deductible_amount": {},
    "coverage_limits": {},
    "exclusions": {},
    "notes": {}
  }
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "service_place_id": "00000000-0000-0000-0000-000000000000",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": 150,
  "billing_period_start": "2024-08-25",
  "billing_period_end": "2024-08-25",
  "last_regularization_date": "2024-08-25",
  "distribution_key_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z",
  "energy_efficiency": {
    "id": "00000000-0000-0000-0000-000000000000",
    "lease_charge_id": "00000000-0000-0000-0000-000000000000",
    "baseline_consumption": 0,
    "target_savings_percentage": 0,
    "monthly_contribution_amount": 0,
    "remaining_months": 0,
    "work_description": "work_description",
    "work_cost": {},
    "energy_audit_reference": {},
    "start_date": "2024-08-25",
    "end_date": "2024-08-25",
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  },
  "insurance": {
    "id": "00000000-0000-0000-0000-000000000000",
    "lease_charge_id": "00000000-0000-0000-0000-000000000000",
    "contract_number": "contract_number",
    "insurance_company": "insurance_company",
    "annual_premium": 0,
    "recoverable_amount": 0,
    "coverage_details": "coverage_details",
    "policy_start_date": "2024-08-25",
    "policy_end_date": "2024-08-25",
    "deductible_amount": {},
    "coverage_limits": {},
    "exclusions": {},
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

application/json

Delete a lease charge

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}

Delete a lease charge › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Delete a lease charge › Responses

Charge deleted successfully

No data returned

DELETE/leases/{lease_id}/charges/{charge_id}

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id

Example Responses

No example specified for this content type

Regularize charge

POST

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/regularize

Perform the regularization of a lease charge

Regularize charge › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Regularize charge › Request Body

Data for charge regularization

regularization_amount

number · decimal

The regularization amount (positive or negative)

Example: 50

regularization_date

string · date

The regularization date

Example: 2024-12-31

notes

string | null · maxLength: 1000

Notes about the regularization

Regularize charge › Responses

Regularization performed successfully

Rental charge

id

string · uuid · required

Unique identifier of the charge

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

calculation_method

string · enum · required

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
FORFAIT requires FORFAIT as calculation basis
DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
PROVISION can be used with all calculation bases
The mode must be allowed for the lease type (allow_provisional, allow_fixed)

Enum values:

FORFAIT

PROVISION

DEPENSE_REELLE

RELEVE_DIRECT

Example: PROVISION

calculation_basis

string · enum · required

Charge calculation basis (specific business rules only).

Compatibility rules:

FORFAIT requires FORFAIT as billing mode
DEPENSE_REELLE requires DEPENSE_REELLE as billing mode or can be used with PROVISION
PERSONNEL_75_POURCENT, PERSONNEL_40_POURCENT, PERSONNEL_100_POURCENT:
- Require the EMPLOYEE category
- Can be used with DEPENSE_REELLE or PROVISION as billing mode

Enum values:

DEPENSE_REELLE

FORFAIT

PERSONNEL_75_POURCENT

PERSONNEL_40_POURCENT

PERSONNEL_100_POURCENT

Example: FORFAIT

amount

number · decimal · min: 0 · required

Charge amount

Example: 150

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

service_place_id

string | null · uuid

Place service ID

category_id

string | null · uuid

Charge category ID

billing_period_start

string | null · date

Billing period start date

billing_period_end

string | null · date

Billing period end date

last_regularization_date

string | null · date

Last regularization date

distribution_key_id

string | null · uuid

Distribution key ID

notes

string | null · maxLength: 1000

Notes about the charge

object

Contribution for sharing energy savings (Energy Transition Act)

object

Insurance taken out by the landlord on behalf of co-tenants

POST/leases/{lease_id}/charges/{charge_id}/regularize

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/regularize \
  --header 'Content-Type: application/json' \
  --data '
{
  "regularization_amount": 50,
  "regularization_date": "2024-12-31",
  "notes": {}
}
'

Example Request Body

{
  "regularization_amount": 50,
  "regularization_date": "2024-12-31",
  "notes": {}
}

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "service_place_id": "00000000-0000-0000-0000-000000000000",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": 150,
  "billing_period_start": "2024-08-25",
  "billing_period_end": "2024-08-25",
  "last_regularization_date": "2024-08-25",
  "distribution_key_id": "00000000-0000-0000-0000-000000000000",
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z",
  "energy_efficiency": {
    "id": "00000000-0000-0000-0000-000000000000",
    "lease_charge_id": "00000000-0000-0000-0000-000000000000",
    "baseline_consumption": 0,
    "target_savings_percentage": 0,
    "monthly_contribution_amount": 0,
    "remaining_months": 0,
    "work_description": "work_description",
    "work_cost": {},
    "energy_audit_reference": {},
    "start_date": "2024-08-25",
    "end_date": "2024-08-25",
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  },
  "insurance": {
    "id": "00000000-0000-0000-0000-000000000000",
    "lease_charge_id": "00000000-0000-0000-0000-000000000000",
    "contract_number": "contract_number",
    "insurance_company": "insurance_company",
    "annual_premium": 0,
    "recoverable_amount": 0,
    "coverage_details": "coverage_details",
    "policy_start_date": "2024-08-25",
    "policy_end_date": "2024-08-25",
    "deductible_amount": {},
    "coverage_limits": {},
    "exclusions": {},
    "notes": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

application/json

Get energy efficiency contribution

GET

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/energy-efficiency

Retrieve the details of the energy efficiency contribution for a charge

Get energy efficiency contribution › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Get energy efficiency contribution › Responses

Energy efficiency contribution retrieved successfully

Contribution for sharing energy savings (Energy Transition Act)

id

string · uuid · required

Unique identifier

lease_charge_id

string · uuid · required

Associated charge ID

baseline_consumption

number · decimal · min: 0 · required

Consumption before works

target_savings_percentage

number · decimal · min: 0 · max: 100 · required

Targeted savings percentage

monthly_contribution_amount

number · decimal · min: 0 · required

Monthly contribution amount

remaining_months

integer · min: 0 · required

Remaining duration in months

work_description

string · required

Description of the completed works

start_date

string · date · required

Contribution start date

end_date

string · date · required

Contribution end date

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

work_cost

number | null · decimal · min: 0

Cost of works

energy_audit_reference

string | null · maxLength: 100

Energy audit reference

notes

string | null · maxLength: 1000

Notes

GET/leases/{lease_id}/charges/{charge_id}/energy-efficiency

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/energy-efficiency

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "lease_charge_id": "00000000-0000-0000-0000-000000000000",
  "baseline_consumption": 0,
  "target_savings_percentage": 0,
  "monthly_contribution_amount": 0,
  "remaining_months": 0,
  "work_description": "work_description",
  "work_cost": {},
  "energy_audit_reference": {},
  "start_date": "2024-08-25",
  "end_date": "2024-08-25",
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

application/json

Update energy efficiency contribution

PUT

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/energy-efficiency

Update the energy efficiency contribution information

Update energy efficiency contribution › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Update energy efficiency contribution › Request Body

Data for updating an energy efficiency contribution

baseline_consumption

number | null · decimal · min: 0

Consumption before works

target_savings_percentage

number | null · decimal · min: 0 · max: 100

Targeted savings percentage (0-100)

monthly_contribution_amount

number | null · decimal · min: 0

Monthly contribution amount

remaining_months

integer | null · min: 0

Remaining duration in months

work_description

string | null · minLength: 1 · maxLength: 1000

Description of the completed works

work_cost

number | null · decimal · min: 0

Cost of works

energy_audit_reference

string | null · maxLength: 100

Energy audit reference

start_date

string | null · date

Contribution start date

end_date

string | null · date

Contribution end date

notes

string | null · maxLength: 1000

Notes

Update energy efficiency contribution › Responses

Energy efficiency contribution updated successfully

Contribution for sharing energy savings (Energy Transition Act)

id

string · uuid · required

Unique identifier

lease_charge_id

string · uuid · required

Associated charge ID

baseline_consumption

number · decimal · min: 0 · required

Consumption before works

target_savings_percentage

number · decimal · min: 0 · max: 100 · required

Targeted savings percentage

monthly_contribution_amount

number · decimal · min: 0 · required

Monthly contribution amount

remaining_months

integer · min: 0 · required

Remaining duration in months

work_description

string · required

Description of the completed works

start_date

string · date · required

Contribution start date

end_date

string · date · required

Contribution end date

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

work_cost

number | null · decimal · min: 0

Cost of works

energy_audit_reference

string | null · maxLength: 100

Energy audit reference

notes

string | null · maxLength: 1000

Notes

PUT/leases/{lease_id}/charges/{charge_id}/energy-efficiency

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/energy-efficiency \
  --header 'Content-Type: application/json' \
  --data '
{
  "baseline_consumption": {},
  "target_savings_percentage": {},
  "monthly_contribution_amount": {},
  "remaining_months": {},
  "work_description": {},
  "work_cost": {},
  "energy_audit_reference": {},
  "start_date": "2024-08-25",
  "end_date": "2024-08-25",
  "notes": {}
}
'

Example Request Body

{
  "baseline_consumption": {},
  "target_savings_percentage": {},
  "monthly_contribution_amount": {},
  "remaining_months": {},
  "work_description": {},
  "work_cost": {},
  "energy_audit_reference": {},
  "start_date": "2024-08-25",
  "end_date": "2024-08-25",
  "notes": {}
}

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "lease_charge_id": "00000000-0000-0000-0000-000000000000",
  "baseline_consumption": 0,
  "target_savings_percentage": 0,
  "monthly_contribution_amount": 0,
  "remaining_months": 0,
  "work_description": "work_description",
  "work_cost": {},
  "energy_audit_reference": {},
  "start_date": "2024-08-25",
  "end_date": "2024-08-25",
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

application/json

Add an energy efficiency contribution

POST

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/energy-efficiency

Add an energy savings sharing contribution to an existing charge

Add an energy efficiency contribution › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Add an energy efficiency contribution › Request Body

Data for creating a new energy efficiency contribution when creating a charge

baseline_consumption

number · decimal · min: 0 · required

Consumption before works

Example: 15000

target_savings_percentage

number · decimal · min: 0 · max: 100 · required

Targeted savings percentage (0-100)

Example: 25

monthly_contribution_amount

number · decimal · min: 0 · required

Monthly contribution amount

Example: 50

duration_months

integer · min: 1 · required

Contribution duration in months

Example: 36

work_description

string · minLength: 1 · maxLength: 1000 · required

Description of the completed works

Example: Attic thermal insulation and boiler replacement

start_date

string · date · required

Contribution start date

Example: 2024-01-01

work_cost

number | null · decimal · min: 0

Cost of works

Example: 18000

energy_audit_reference

string | null · maxLength: 100

Energy audit reference

Example: DPE-2024-001234

notes

string | null · maxLength: 1000

Notes

Add an energy efficiency contribution › Responses

Energy efficiency contribution created successfully

Contribution for sharing energy savings (Energy Transition Act)

id

string · uuid · required

Unique identifier

lease_charge_id

string · uuid · required

Associated charge ID

baseline_consumption

number · decimal · min: 0 · required

Consumption before works

target_savings_percentage

number · decimal · min: 0 · max: 100 · required

Targeted savings percentage

monthly_contribution_amount

number · decimal · min: 0 · required

Monthly contribution amount

remaining_months

integer · min: 0 · required

Remaining duration in months

work_description

string · required

Description of the completed works

start_date

string · date · required

Contribution start date

end_date

string · date · required

Contribution end date

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

work_cost

number | null · decimal · min: 0

Cost of works

energy_audit_reference

string | null · maxLength: 100

Energy audit reference

notes

string | null · maxLength: 1000

Notes

POST/leases/{lease_id}/charges/{charge_id}/energy-efficiency

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/energy-efficiency \
  --header 'Content-Type: application/json' \
  --data '
{
  "baseline_consumption": 15000,
  "target_savings_percentage": 25,
  "monthly_contribution_amount": 50,
  "duration_months": 36,
  "work_description": "Attic thermal insulation and boiler replacement",
  "work_cost": 18000,
  "energy_audit_reference": "DPE-2024-001234",
  "start_date": "2024-01-01",
  "notes": {}
}
'

Example Request Body

{
  "baseline_consumption": 15000,
  "target_savings_percentage": 25,
  "monthly_contribution_amount": 50,
  "duration_months": 36,
  "work_description": "Attic thermal insulation and boiler replacement",
  "work_cost": 18000,
  "energy_audit_reference": "DPE-2024-001234",
  "start_date": "2024-01-01",
  "notes": {}
}

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "lease_charge_id": "00000000-0000-0000-0000-000000000000",
  "baseline_consumption": 0,
  "target_savings_percentage": 0,
  "monthly_contribution_amount": 0,
  "remaining_months": 0,
  "work_description": "work_description",
  "work_cost": {},
  "energy_audit_reference": {},
  "start_date": "2024-08-25",
  "end_date": "2024-08-25",
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

application/json

Delete energy efficiency contribution

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/energy-efficiency

Delete the energy efficiency contribution from a charge

Delete energy efficiency contribution › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Delete energy efficiency contribution › Responses

Energy efficiency contribution deleted successfully

No data returned

DELETE/leases/{lease_id}/charges/{charge_id}/energy-efficiency

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/energy-efficiency

Example Responses

No example specified for this content type

Get shared housing insurance

GET

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/insurance

Retrieve the details of the shared housing insurance for a charge

Get shared housing insurance › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Get shared housing insurance › Responses

Shared housing insurance retrieved successfully

Insurance taken out by the landlord on behalf of co-tenants

id

string · uuid · required

Unique identifier

lease_charge_id

string · uuid · required

Associated charge ID

contract_number

string · maxLength: 100 · required

Insurance contract number

insurance_company

string · maxLength: 200 · required

Insurance company

annual_premium

number · decimal · min: 0 · required

Annual premium

recoverable_amount

number · decimal · min: 0 · required

Amount recoverable from tenants

coverage_details

string · required

Coverage details

policy_start_date

string · date · required

Policy start date

policy_end_date

string · date · required

Policy end date

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

deductible_amount

number | null · decimal · min: 0

Deductible amount

object | null

Coverage limits (JSON)

exclusions

string | null · maxLength: 1000

Coverage exclusions

notes

string | null · maxLength: 1000

Notes

GET/leases/{lease_id}/charges/{charge_id}/insurance

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/insurance

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "lease_charge_id": "00000000-0000-0000-0000-000000000000",
  "contract_number": "contract_number",
  "insurance_company": "insurance_company",
  "annual_premium": 0,
  "recoverable_amount": 0,
  "coverage_details": "coverage_details",
  "policy_start_date": "2024-08-25",
  "policy_end_date": "2024-08-25",
  "deductible_amount": {},
  "coverage_limits": {},
  "exclusions": {},
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

application/json

Update shared housing insurance

PUT

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/insurance

Update the shared housing insurance information

Update shared housing insurance › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Update shared housing insurance › Request Body

Data for updating a co-tenancy insurance

contract_number

string | null · minLength: 1 · maxLength: 100

Insurance contract number

insurance_company

string | null · minLength: 1 · maxLength: 200

Insurance company

annual_premium

number | null · decimal · min: 0

Annual premium

recoverable_amount

number | null · decimal · min: 0

Amount recoverable from tenants

coverage_details

string | null · minLength: 1 · maxLength: 2000

Coverage details

policy_start_date

string | null · date

Policy start date

policy_end_date

string | null · date

Policy end date

deductible_amount

number | null · decimal · min: 0

Deductible amount

object | null

Coverage limits (JSON)

exclusions

string | null · maxLength: 1000

Coverage exclusions

notes

string | null · maxLength: 1000

Notes

Update shared housing insurance › Responses

Shared housing insurance updated successfully

Insurance taken out by the landlord on behalf of co-tenants

id

string · uuid · required

Unique identifier

lease_charge_id

string · uuid · required

Associated charge ID

contract_number

string · maxLength: 100 · required

Insurance contract number

insurance_company

string · maxLength: 200 · required

Insurance company

annual_premium

number · decimal · min: 0 · required

Annual premium

recoverable_amount

number · decimal · min: 0 · required

Amount recoverable from tenants

coverage_details

string · required

Coverage details

policy_start_date

string · date · required

Policy start date

policy_end_date

string · date · required

Policy end date

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

deductible_amount

number | null · decimal · min: 0

Deductible amount

object | null

Coverage limits (JSON)

exclusions

string | null · maxLength: 1000

Coverage exclusions

notes

string | null · maxLength: 1000

Notes

PUT/leases/{lease_id}/charges/{charge_id}/insurance

curl --request PUT \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/insurance \
  --header 'Content-Type: application/json' \
  --data '
{
  "contract_number": {},
  "insurance_company": {},
  "annual_premium": {},
  "recoverable_amount": {},
  "coverage_details": {},
  "policy_start_date": "2024-08-25",
  "policy_end_date": "2024-08-25",
  "deductible_amount": {},
  "coverage_limits": {},
  "exclusions": {},
  "notes": {}
}
'

Example Request Body

{
  "contract_number": {},
  "insurance_company": {},
  "annual_premium": {},
  "recoverable_amount": {},
  "coverage_details": {},
  "policy_start_date": "2024-08-25",
  "policy_end_date": "2024-08-25",
  "deductible_amount": {},
  "coverage_limits": {},
  "exclusions": {},
  "notes": {}
}

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "lease_charge_id": "00000000-0000-0000-0000-000000000000",
  "contract_number": "contract_number",
  "insurance_company": "insurance_company",
  "annual_premium": 0,
  "recoverable_amount": 0,
  "coverage_details": "coverage_details",
  "policy_start_date": "2024-08-25",
  "policy_end_date": "2024-08-25",
  "deductible_amount": {},
  "coverage_limits": {},
  "exclusions": {},
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

application/json

Add shared housing insurance

POST

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/insurance

Add a shared housing insurance taken out by the landlord to an existing charge

Add shared housing insurance › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Add shared housing insurance › Request Body

Data for creating a new co-tenancy insurance when creating a charge

contract_number

string · minLength: 1 · maxLength: 100 · required

Insurance contract number

Example: ASS-COL-2024-001

insurance_company

string · minLength: 1 · maxLength: 200 · required

Insurance company

Example: AXA Assurances

annual_premium

number · decimal · min: 0 · required

Annual premium

Example: 1200

recoverable_amount

number · decimal · min: 0 · required

Amount recoverable from tenants (less than or equal to annual premium)

Example: 1200

coverage_details

string · minLength: 1 · maxLength: 2000 · required

Coverage details

Example: Civil liability, water damage, fire

policy_start_date

string · date · required

Policy start date

Example: 2024-01-01

policy_end_date

string · date · required

Policy end date (must be after start date)

Example: 2024-12-31

deductible_amount

number | null · decimal · min: 0

Deductible amount

Example: 150

object | null

Coverage limits (JSON)

Example: {"civil_liability":2000000,"water_damage":50000}

exclusions

string | null · maxLength: 1000

Coverage exclusions

Example: Intentional damage, undeclared natural disasters

notes

string | null · maxLength: 1000

Notes

Add shared housing insurance › Responses

Shared housing insurance created successfully

Insurance taken out by the landlord on behalf of co-tenants

id

string · uuid · required

Unique identifier

lease_charge_id

string · uuid · required

Associated charge ID

contract_number

string · maxLength: 100 · required

Insurance contract number

insurance_company

string · maxLength: 200 · required

Insurance company

annual_premium

number · decimal · min: 0 · required

Annual premium

recoverable_amount

number · decimal · min: 0 · required

Amount recoverable from tenants

coverage_details

string · required

Coverage details

policy_start_date

string · date · required

Policy start date

policy_end_date

string · date · required

Policy end date

created_at

string · date-time · required

Creation date

updated_at

string · date-time · required

Last modification date

deductible_amount

number | null · decimal · min: 0

Deductible amount

object | null

Coverage limits (JSON)

exclusions

string | null · maxLength: 1000

Coverage exclusions

notes

string | null · maxLength: 1000

Notes

POST/leases/{lease_id}/charges/{charge_id}/insurance

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/insurance \
  --header 'Content-Type: application/json' \
  --data '
{
  "contract_number": "ASS-COL-2024-001",
  "insurance_company": "AXA Assurances",
  "annual_premium": 1200,
  "recoverable_amount": 1200,
  "coverage_details": "Civil liability, water damage, fire",
  "policy_start_date": "2024-01-01",
  "policy_end_date": "2024-12-31",
  "deductible_amount": 150,
  "coverage_limits": {
    "civil_liability": 2000000,
    "water_damage": 50000
  },
  "exclusions": "Intentional damage, undeclared natural disasters",
  "notes": {}
}
'

Example Request Body

{
  "contract_number": "ASS-COL-2024-001",
  "insurance_company": "AXA Assurances",
  "annual_premium": 1200,
  "recoverable_amount": 1200,
  "coverage_details": "Civil liability, water damage, fire",
  "policy_start_date": "2024-01-01",
  "policy_end_date": "2024-12-31",
  "deductible_amount": 150,
  "coverage_limits": {
    "civil_liability": 2000000,
    "water_damage": 50000
  },
  "exclusions": "Intentional damage, undeclared natural disasters",
  "notes": {}
}

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "lease_charge_id": "00000000-0000-0000-0000-000000000000",
  "contract_number": "contract_number",
  "insurance_company": "insurance_company",
  "annual_premium": 0,
  "recoverable_amount": 0,
  "coverage_details": "coverage_details",
  "policy_start_date": "2024-08-25",
  "policy_end_date": "2024-08-25",
  "deductible_amount": {},
  "coverage_limits": {},
  "exclusions": {},
  "notes": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

application/json

Delete shared housing insurance

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/charges/{charge_id}/insurance

Delete the shared housing insurance from a charge

Delete shared housing insurance › path Parameters

lease_id

string · uuid · required

Lease ID

charge_id

string · uuid · required

Charge ID

Delete shared housing insurance › Responses

Shared housing insurance deleted successfully

No data returned

DELETE/leases/{lease_id}/charges/{charge_id}/insurance

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/charges/:charge_id/insurance

Example Responses

No example specified for this content type

Generate a lease PDF

POST

https://api.faireplace.com/api

/leases/{lease_id}/pdf

Generates a PDF document from a lease template with the provided data. Returns the PDF directly as binary with performance headers.

Generate a lease PDF › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

Generate a lease PDF › Request Body

Request to generate a lease PDF

template_id

string · uuid · required

Document template ID to use

Example: 550e8400-e29b-41d4-a716-446655440000

template_type

string · enum · required

Template type (LeaseContract, Amendment, InventoryReport, etc.)

Enum values:

LeaseContract

Amendment

InventoryReport

RentReceipt

NoticeToVacate

OtherDocument

Example: LeaseContract

object · required

Data to insert into the template (JSON format)

Example: {"tenant_name":"Jean Dupont","property_address":"123 Rue de la Paix, 75001 Paris","rent_amount":850}

object

PDF formatting options

Generate a lease PDF › Responses

PDF generated successfully

string

POST/leases/{lease_id}/pdf

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/pdf \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "template_type": "LeaseContract",
  "data": {
    "tenant_name": "Jean Dupont",
    "property_address": "123 Rue de la Paix, 75001 Paris",
    "rent_amount": 850
  },
  "format_options": {
    "paper_size": "A4",
    "margins": {
      "top": 25,
      "right": 25,
      "bottom": 25,
      "left": 25
    },
    "font_size": 12,
    "add_metadata": true,
    "custom_variables": {},
    "pdf_standard": "PDF/A-1b",
    "page_ranges": [
      "1-5",
      "10"
    ],
    "compress": false,
    "add_form_fields": false,
    "custom_form_fields": {}
  }
}
'

Example Request Body

{
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "template_type": "LeaseContract",
  "data": {
    "tenant_name": "Jean Dupont",
    "property_address": "123 Rue de la Paix, 75001 Paris",
    "rent_amount": 850
  },
  "format_options": {
    "paper_size": "A4",
    "margins": {
      "top": 25,
      "right": 25,
      "bottom": 25,
      "left": 25
    },
    "font_size": 12,
    "add_metadata": true,
    "custom_variables": {},
    "pdf_standard": "PDF/A-1b",
    "page_ranges": [
      "1-5",
      "10"
    ],
    "compress": false,
    "add_form_fields": false,
    "custom_form_fields": {}
  }
}

Example Responses

string

application/pdf

List lease PDFs

GET

https://api.faireplace.com/api

/leases/{lease_id}/pdfs

Retrieves the list of all generated PDFs for a specific lease

List lease PDFs › path Parameters

lease_id

string · uuid · required

Unique lease ID

Example: 550e8400-e29b-41d4-a716-446655440000

List lease PDFs › Responses

PDF list retrieved successfully

object[]

Generated PDF metadata

id

string · uuid · required

Unique identifier of the generated PDF

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Associated lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

template_id

string · uuid · required

Template ID used

Example: 550e8400-e29b-41d4-a716-446655440002

template_type

string · enum · required

Template type used

Enum values:

LeaseContract

Amendment

InventoryReport

RentReceipt

NoticeToVacate

OtherDocument

Example: LeaseContract

file_path

string · required

Path or URL of the generated PDF file

Example: https://storage.example.com/pdfs/lease_contract_123.pdf

file_size

integer · int64 · min: 0 · required

File size in bytes

Example: 524288

creation_timestamp

string · date-time · required

PDF creation date and time

Example: 2024-01-15T10:30:00Z

object | null

Custom variables used during generation

GET/leases/{lease_id}/pdfs

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/pdfs

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "lease_id": "550e8400-e29b-41d4-a716-446655440001",
    "template_id": "550e8400-e29b-41d4-a716-446655440002",
    "template_type": "LeaseContract",
    "file_path": "https://storage.example.com/pdfs/lease_contract_123.pdf",
    "file_size": 524288,
    "creation_timestamp": "2024-01-15T10:30:00Z",
    "custom_variables": {}
  }
]

application/json

Download a lease PDF

GET

https://api.faireplace.com/api

/leases/pdf/{pdf_id}

Downloads a generated PDF document for a lease

Download a lease PDF › path Parameters

pdf_id

string · uuid · required

Unique generated PDF ID

Example: 550e8400-e29b-41d4-a716-446655440000

Download a lease PDF › Responses

PDF downloaded successfully

string

GET/leases/pdf/{pdf_id}

curl --request GET \
  --url https://api.faireplace.com/api/leases/pdf/:pdf_id

Example Responses

string

application/pdf

Delete a lease PDF

DELETE

https://api.faireplace.com/api

/leases/pdf/{pdf_id}

Deletes a generated PDF document for a lease

Delete a lease PDF › path Parameters

pdf_id

string · uuid · required

Unique generated PDF ID

Example: 550e8400-e29b-41d4-a716-446655440000

Delete a lease PDF › Responses

PDF deleted successfully

message

string

DELETE/leases/pdf/{pdf_id}

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/pdf/:pdf_id

Example Responses

{
  "message": "PDF deleted successfully"
}

application/json

PDF cache statistics

GET

https://api.faireplace.com/api

/leases/cache/stats

Retrieves PDF generation cache statistics

PDF cache statistics › Responses

Cache statistics retrieved successfully

hit_count

integer

Number of cache hits

Example: 42

miss_count

integer

Number of cache misses

Example: 8

size

integer

Number of cache entries

Example: 15

GET/leases/cache/stats

curl --request GET \
  --url https://api.faireplace.com/api/leases/cache/stats

Example Responses

{
  "hit_count": 42,
  "miss_count": 8,
  "size": 15
}

application/json

Clear PDF cache

POST

https://api.faireplace.com/api

/leases/cache/clear

Clears the PDF generation cache

Clear PDF cache › Responses

Cache cleared successfully

message

string

cleared_entries

integer

Number of entries removed from cache

Example: 15

POST/leases/cache/clear

curl --request POST \
  --url https://api.faireplace.com/api/leases/cache/clear

Example Responses

{
  "message": "PDF cache cleared successfully",
  "cleared_entries": 15
}

application/json

Initiate electronic signature (global level)

POST

https://api.faireplace.com/api

/leases/signatures/initiate

Initiates the electronic signature process for a lease.

Signer identification

The system automatically identifies the initiating signer via:

The auth_user_id extracted from the JWT (claim sub)
Matching with an owner_id or lessee_id in the database
The signer type (owner or tenant) is determined automatically

Verification at individual signer level

The system now verifies at the individual signer level rather than at the global document level:

If you have already signed: you cannot restart (error 409)
If the document is fully signed: you cannot restart (error 409)
If a signature is in progress for you: you must wait (error 409)
If another signer has signed: you can continue the process (partial restart allowed)

Partial restart

If only one signer has signed, the other signer can initiate a new signature. This allows continuing the process even if one signer has already completed their signature.

Generates the PDF, creates signature requests for all signers (owner + tenants).

Initiate electronic signature (global level) › Request Body

lease_id

string · uuid · required

Lease ID to be signed

Example: 550e8400-e29b-41d4-a716-446655440000

Initiate electronic signature (global level) › Responses

Signature initiated successfully

Response after initiating a signature

document_signature_id

string · uuid · required

Unique ID of the signature process

Example: 550e8400-e29b-41d4-a716-446655440000

event_id

string · required

Unique event ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

pdf_url

string · uri · required

Absolute URL of the PDF document to sign

Example: https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002

media_id

string · uuid · required

Reference to the media table (PDF document)

Example: 550e8400-e29b-41d4-a716-446655440002

object[] · minItems: 1 · required

List of created signature requests

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

POST/leases/signatures/initiate

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/initiate \
  --header 'Content-Type: application/json' \
  --data '
{
  "lease_id": "550e8400-e29b-41d4-a716-446655440000"
}
'

Example Request Body

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440000"
}

Example Responses

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "signature_550e8400-e29b-41d4-a716-446655440001_1704985200",
  "pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002",
  "media_id": "550e8400-e29b-41d4-a716-446655440002",
  "signature_requests": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "signer_type": "PROPRIETAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "signer_type": "LOCATAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "SIGNING"
}

application/json

deprecated

Get signature status (global route - deprecated)

GET

https://api.faireplace.com/api

/leases/signatures/status

Retrieves the current status of an electronic signature process. Note: This global route requires a lease_id as a query parameter. It is recommended to use the specific route /leases/{lease_id}/signature/status instead.

Get signature status (global route - deprecated) › query Parameters

lease_id

string · uuid · required

Lease ID

Get signature status (global route - deprecated) › Responses

Status retrieved successfully

Status of a signature process (returned by get_signature_status with DO Global)

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

object · required

Signature state from DO Global (dynamic structure)

Example: {"status":"SIGNING","signers":[{"signer_type":"PROPRIETAIRE","status":"COMPLETED"},{"signer_type":"LOCATAIRE","status":"PENDING"}]}

GET/leases/signatures/status

curl --request GET \
  --url 'https://api.faireplace.com/api/leases/signatures/status?lease_id=%3Cstring%3E'

Example Responses

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": {
    "status": "SIGNING",
    "signers": [
      {
        "signer_type": "PROPRIETAIRE",
        "status": "COMPLETED"
      },
      {
        "signer_type": "LOCATAIRE",
        "status": "PENDING"
      }
    ]
  }
}

application/json

Status of a specific document

GET

https://api.faireplace.com/api

/leases/signatures/document/{document_signature_id}/status

Retrieves the detailed status of a signature process by its ID (global route)

Status of a specific document › path Parameters

document_signature_id

string · uuid · required

Signature process ID

Status of a specific document › Responses

Status retrieved successfully

Detailed status of a signature document (returned by get_document_signature_status)

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

event_id

string · required

Unique ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

pdf_url

string · uri · required

PDF document URL

Example: https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002

media_id

string · uuid · required

Reference to the media table

Example: 550e8400-e29b-41d4-a716-446655440002

object[] · required

List of signature requests

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

GET/leases/signatures/document/{document_signature_id}/status

curl --request GET \
  --url https://api.faireplace.com/api/leases/signatures/document/:document_signature_id/status

Example Responses

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "signature_550e8400-e29b-41d4-a716-446655440001_1704985200",
  "pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002",
  "media_id": "550e8400-e29b-41d4-a716-446655440002",
  "signature_requests": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signer_type": "PROPRIETAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "READY"
}

application/json

List all contracts pending signature

GET

https://api.faireplace.com/api

/leases/signatures/pending

Retrieves the paginated list of all contracts pending signature for the tenant.

Access

This endpoint is for users with the "owner" role in the tenant. It returns all contracts where at least one signer has a PENDING or SIGNING status.

Automatic filtering

Only contracts from the authenticated user's tenant are returned (multi-tenant isolation)
Contracts with COMPLETED, EXPIRED, or CANCELLED status are excluded
Only contracts with at least one pending signer are returned

Returned information

For each contract, you receive:

Document information (ID, lease, status, dates, URLs)
Complete list of all signers with their individual statuses
The URL of the PDF document to sign
The URL of the signed PDF (if available)

Pagination

Use limit and offset to paginate results. The total_count field indicates the total number of matching contracts.

List all contracts pending signature › query Parameters

limit

integer · min: 1 · max: 100

Maximum number of results per page (default: 50, max: 100)

Default: 50

offset

integer · min: 0

Number of results to skip for pagination (default: 0)

Default: 0

List all contracts pending signature › Responses

Pending contracts list retrieved successfully

Paginated response containing the list of contracts pending signature for the tenant. Used by the `GET /leases/signatures/pending` endpoint. ## Pagination Use the `limit` and `offset` fields in the request to navigate through results. The `total_count` field indicates the total number of contracts matching the criteria, allowing you to calculate the number of pages. ## Page calculation example ``` total_pages = ceil(total_count / limit) current_page = floor(offset / limit) + 1 ```

object[] · required

List of contracts pending signature (for the current page)

total_count

integer · int64 · min: 0 · required

Total number of pending contracts (all combined, before pagination)

Example: 25

limit

integer · min: 1 · max: 100 · required

Maximum number of results per page (value used for the request)

Example: 50

Default: 50

offset

integer · min: 0 · required

Number of skipped results (pagination offset used)

Example: 0

Default: 0

GET/leases/signatures/pending

curl --request GET \
  --url https://api.faireplace.com/api/leases/signatures/pending

Example Responses

{
  "contracts": [
    {
      "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
      "lease_id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "SIGNING",
      "initiator_type": "PROPRIETAIRE",
      "created_at": "2024-01-15T10:00:00Z",
      "expires_at": "2024-01-22T10:00:00Z",
      "document_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002",
      "signed_pdf_url": null,
      "signers": [
        {
          "signer_type": "PROPRIETAIRE",
          "signer_email": "[email protected]",
          "signer_phone": "+33612345678",
          "status": "PENDING",
          "expires_at": "2024-01-22T10:00:00Z",
          "first_name": "Jean",
          "last_name": "Dupont",
          "title": "Mr."
        },
        {
          "signer_type": "LOCATAIRE",
          "signer_email": "[email protected]",
          "signer_phone": "+33612345679",
          "status": "COMPLETED",
          "expires_at": "2024-01-22T10:00:00Z",
          "first_name": "Marie",
          "last_name": "Martin",
          "title": "Mrs."
        }
      ]
    }
  ],
  "total_count": 1,
  "limit": 50,
  "offset": 0
}

application/json

Signature contract details

GET

https://api.faireplace.com/api

/leases/signatures/contracts/{document_signature_id}

Retrieves the complete details of a signature contract, including all signers and their statuses

Signature contract details › path Parameters

document_signature_id

string · uuid · required

Signature process ID

Signature contract details › Responses

Details retrieved successfully

Full details of a signature contract

document_signature_id

string · uuid · required

lease_id

string · uuid · required

media_id

string · uuid · required

Reference to the media table

Example: 550e8400-e29b-41d4-a716-446655440002

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

initiator_type

string · enum · required

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

initiator_id

string · uuid · required

Initiator ID

Example: 550e8400-e29b-41d4-a716-446655440003

event_id

string · required

Unique ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

created_at

string · date-time · required

object[] · minItems: 1 · required

expires_at

string | null · date-time

document_url

string | null · uri

signed_pdf_url

string | null · uri

archive_url

string | null · uri

URL of the archived PDF with electronic timestamping

Example: https://storage.example.com/leases/archived-doc.pdf

GET/leases/signatures/contracts/{document_signature_id}

curl --request GET \
  --url https://api.faireplace.com/api/leases/signatures/contracts/:document_signature_id

Example Responses

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "media_id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "READY",
  "initiator_type": "PROPRIETAIRE",
  "initiator_id": "550e8400-e29b-41d4-a716-446655440003",
  "event_id": "signature_550e8400-e29b-41d4-a716-446655440001_1704985200",
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-01-20T10:00:00Z",
  "signers": [
    {
      "signer_type": "PROPRIETAIRE",
      "signer_email": "[email protected]",
      "signer_phone": "+33612345678",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z",
      "signed_at": "2024-01-16T15:30:00Z",
      "first_name": "Jean",
      "last_name": "Dupont",
      "legal_name": "SARL Dupont Immobilier",
      "title": "M."
    }
  ],
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signed_pdf_url": "https://storage.example.com/leases/signed-doc.pdf",
  "archive_url": "https://storage.example.com/leases/archived-doc.pdf"
}

application/json

Request a signature (send OTP) - Global route

POST

https://api.faireplace.com/api

/leases/signatures/request

Requests a signer's signature by sending an OTP code via SMS. The person_id (owner_id or lessee_id) is automatically resolved from the JWT (auth_user_id). Minimal structure: document_signature_id and signature_data.signature_image.

Request a signature (send OTP) - Global route › Request Body

Request to initiate a user's signature. This object is sent to the `/leases/{lease_id}/signature/request` endpoint to: 1. Submit the signature image captured by the user 2. Trigger sending an OTP code via SMS The user is automatically identified via their JWT - no need to specify their identity in the request.

document_signature_id

string · uuid · required

Unique identifier of the signature process. Obtained during initiation via /signature/initiate.

Example: 550e8400-e29b-41d4-a716-446655440000

object · required

Handwritten signature data

Request a signature (send OTP) - Global route › Responses

OTP sent successfully

Dynamic response from DO Global

POST/leases/signatures/request

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }
}
'

Example Request Body

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }
}

application/json

Example Responses

{
  "success": true,
  "message": "OTP code sent via SMS",
  "expires_at": "2024-01-15T10:15:00Z"
}

application/json

Process a signature event

POST

https://api.faireplace.com/api

/leases/signatures/events/process

Processes a signature request event received from the notifier function (used by webhooks)

Process a signature event › Request Body

Signature request event (format aligned with the notifier function)

object · required

Base event for Scaleway Topics

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

object · required

Signer information

document_url

string · uri · required

URL of the PDF document to sign

Example: https://storage.example.com/leases/unsigned-doc.pdf

signature_url

string · uri · required

URL to access the signature

Example: https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000

expires_at

string · date-time · required

Signature request expiration date

Example: 2024-01-22T10:00:00Z

Process a signature event › Responses

Event processed successfully

status

string

event_id

string

The processed event ID

Example: evt_550e8400-e29b-41d4-a716-446655440000

document_signature_id

string · uuid

lease_id

string · uuid

signer_email

string · email

signer_type

string · enum

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

POST/leases/signatures/events/process

curl --request POST \
  --url https://api.faireplace.com/api/leases/signatures/events/process \
  --header 'Content-Type: application/json' \
  --data '
{
  "base": {
    "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "event_type": "SignatureRequested",
    "timestamp": "2024-01-15T10:00:00Z",
    "correlation_id": "corr_550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "metadata": {}
  },
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_info": {
    "signer_type": "PROPRIETAIRE",
    "phone": "+33612345678",
    "email": "[email protected]",
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "last_name": "Dupont",
    "legal_name": "SARL Dupont Immobilier",
    "title": "M."
  },
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signature_url": "https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:00:00Z"
}
'

Example Request Body

{
  "base": {
    "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "event_type": "SignatureRequested",
    "timestamp": "2024-01-15T10:00:00Z",
    "correlation_id": "corr_550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "metadata": {}
  },
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_info": {
    "signer_type": "PROPRIETAIRE",
    "phone": "+33612345678",
    "email": "[email protected]",
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "last_name": "Dupont",
    "legal_name": "SARL Dupont Immobilier",
    "title": "M."
  },
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signature_url": "https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:00:00Z"
}

Example Responses

{
  "status": "processed",
  "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_email": "[email protected]",
  "signer_type": "PROPRIETAIRE"
}

application/json

Initiate signature for a specific lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/initiate

Initiates the electronic signature process directly from the context of a lease.

Signer identification

The system automatically identifies the initiating signer via:

The auth_user_id extracted from the JWT (claim sub)
Matching with an owner_id or lessee_id in the database
The signer type (owner or tenant) is determined automatically

Verification at individual signer level

The system now verifies at the individual signer level rather than at the global document level:

If you have already signed: you cannot restart (error 409)
If the document is fully signed: you cannot restart (error 409)
If a signature is in progress for you: you must wait (error 409)
If another signer has signed: you can continue the process (partial restart allowed)

Partial restart

If only one signer has signed, the other signer can initiate a new signature. This allows continuing the process even if one signer has already completed their signature.

PDF generation

Generates the PDF, creates signature requests for all signers (owner + tenants).

Initiate signature for a specific lease › path Parameters

lease_id

string · uuid · required

Lease ID

Initiate signature for a specific lease › Request Body optional

Initiate signature for a specific lease › Responses

Signature initiated successfully

Response after initiating a signature

document_signature_id

string · uuid · required

Unique ID of the signature process

Example: 550e8400-e29b-41d4-a716-446655440000

event_id

string · required

Unique event ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

pdf_url

string · uri · required

Absolute URL of the PDF document to sign

Example: https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002

media_id

string · uuid · required

Reference to the media table (PDF document)

Example: 550e8400-e29b-41d4-a716-446655440002

object[] · minItems: 1 · required

List of created signature requests

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

POST/leases/{lease_id}/signature/initiate

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/initiate \
  --header 'Content-Type: application/json' \
  --data '{}'

Example Request Body

{}

Example Responses

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "signature_550e8400-e29b-41d4-a716-446655440001_1704985200",
  "pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002",
  "media_id": "550e8400-e29b-41d4-a716-446655440002",
  "signature_requests": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "signer_type": "PROPRIETAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "signer_type": "LOCATAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "SIGNING"
}

application/json

Signature status of a lease

GET

https://api.faireplace.com/api

/leases/{lease_id}/signature/status

Retrieves the signature status for this specific lease. This route fetches the latest document_signature for the lease and queries DO Global to obtain the current state of the signature.

Signature status of a lease › path Parameters

lease_id

string · uuid · required

Lease ID

Signature status of a lease › Responses

Status retrieved successfully

Status of a signature process (returned by get_signature_status with DO Global)

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

object · required

Signature state from DO Global (dynamic structure)

Example: {"status":"SIGNING","signers":[{"signer_type":"PROPRIETAIRE","status":"COMPLETED"},{"signer_type":"LOCATAIRE","status":"PENDING"}]}

GET/leases/{lease_id}/signature/status

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/status

Example Responses

{
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": {
    "status": "SIGNING",
    "signers": [
      {
        "signer_type": "PROPRIETAIRE",
        "status": "COMPLETED"
      },
      {
        "signer_type": "LOCATAIRE",
        "status": "PENDING"
      }
    ]
  }
}

application/json

Status of a specific signature document

GET

https://api.faireplace.com/api

/leases/{lease_id}/signature/document/{document_signature_id}/status

Retrieves the detailed status of a signature process by its ID in the context of a lease

Status of a specific signature document › path Parameters

lease_id

string · uuid · required

Lease ID

document_signature_id

string · uuid · required

Signature process ID

Status of a specific signature document › Responses

Status retrieved successfully

Detailed status of a signature document (returned by get_document_signature_status)

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

event_id

string · required

Unique ID for traceability

Example: signature_550e8400-e29b-41d4-a716-446655440001_1704985200

pdf_url

string · uri · required

PDF document URL

Example: https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002

media_id

string · uuid · required

Reference to the media table

Example: 550e8400-e29b-41d4-a716-446655440002

object[] · required

List of signature requests

status

string · enum · required

Status of the document signature process

Enum values:

READY

SIGNING

COMPLETED

FAILED

ARCHIVED

Example: READY

GET/leases/{lease_id}/signature/document/{document_signature_id}/status

curl --request GET \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/document/:document_signature_id/status

Example Responses

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "signature_550e8400-e29b-41d4-a716-446655440001_1704985200",
  "pdf_url": "https://api.faireplace.com/api/media/serve/550e8400-e29b-41d4-a716-446655440002",
  "media_id": "550e8400-e29b-41d4-a716-446655440002",
  "signature_requests": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signer_type": "PROPRIETAIRE",
      "signer_email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2024-01-20T10:00:00Z"
    }
  ],
  "status": "READY"
}

application/json

Request a signature - Send an OTP via SMS

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/request

Initiates the signature process for the authenticated user by sending an OTP code via SMS.

Signature flow

The user captures their signature image (handwritten drawing)
The image is encoded in base64 and sent with this endpoint
The system identifies the user via their JWT and verifies they are a signer of the lease
A 6-digit OTP code is sent via SMS to the registered phone number
The code expires after 5 minutes

User identification

The system automatically identifies the user as a signer via:

The auth_user_id extracted from the JWT (claim sub)
Matching with an owner_id or lessee_id in the database

Prerequisites

The user must be authenticated and be a signer of the lease
The signature process must have been initiated (/signature/initiate)
The signer must have a valid registered phone number

Signature image

The image must be:

Encoded in base64
PNG or JPEG format recommended
Reasonable size (< 500KB after encoding)

Request a signature - Send an OTP via SMS › path Parameters

lease_id

string · uuid · required

UUID identifier of the lease

Request a signature - Send an OTP via SMS › Request Body

document_signature_id

string · uuid · required

Unique identifier of the signature process. Obtained during initiation via /signature/initiate.

Example: 550e8400-e29b-41d4-a716-446655440000

object · required

Handwritten signature data

Request a signature - Send an OTP via SMS › Responses

OTP code sent successfully via SMS

success

boolean · required

Indicates whether the sending was successful

Example: true

message

string · required

Confirmation message

Example: OTP code sent by SMS

expires_at

string · date-time

OTP code expiration date (typically 5 minutes)

Example: 2024-01-15T10:15:00Z

phone_hint

string

Phone number hint (partially masked)

Example: +33 6 ** ** ** 78

POST/leases/{lease_id}/signature/request

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAACoCAMAAABt9SM9AAAABGdBTUEAALGPC..."
  }
}
'

Example Request Body

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_data": {
    "signature_image": "iVBORw0KGgoAAAANSUhEUgAAASwAAACoCAMAAABt9SM9AAAABGdBTUEAALGPC..."
  }
}

application/json

Example Responses

{
  "success": true,
  "message": "OTP code sent via SMS to +33 6 ** ** ** 78",
  "expires_at": "2024-01-15T10:15:00Z"
}

application/json

Validate OTP and apply electronic signature

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/validate-otp

Validates the OTP code received via SMS and applies the electronic signature to the PDF document.

Validation flow

The user enters the 6-digit OTP code received via SMS
The system verifies that the code is valid and not expired
If valid, the signature (previously captured image) is applied to the PDF
The signer's status changes to COMPLETED
If all signers have signed, the final document is generated

User identification

The system automatically identifies the user as a signer via:

The auth_user_id extracted from the JWT (claim sub)
Matching with an owner_id or lessee_id in the database
Verification that this user is indeed a signer of the lease

OTP code expiration

The OTP code expires after 5 minutes. If the code has expired, the user must request a new code via /signature/request.

Final document

When all signers have validated their signature:

The signed PDF is generated with all signatures
The signed PDF URL is returned in signed_pdf_url
The document status changes to COMPLETED
A notification is sent to all signers

Validate OTP and apply electronic signature › path Parameters

lease_id

string · uuid · required

UUID identifier of the lease

Validate OTP and apply electronic signature › Request Body

Request to validate the OTP code and finalize the signature. This object is sent to the `/leases/{lease_id}/signature/validate-otp` endpoint after the user has received their code via SMS. The OTP code expires after **5 minutes**. If expired, the user must request a new code via `/signature/request`.

document_signature_id

string · uuid · required

Unique identifier of the signature process. Must match the one used during the signature request.

Example: 550e8400-e29b-41d4-a716-446655440000

otp

string · minLength: 6 · maxLength: 6 · pattern: ^\d{6}$ · required

6-digit OTP code received via SMS.

Format: Exactly 6 digits (0-9) Validity: 5 minutes after sending Attempts: Maximum 3 attempts before temporary lockout

Example: 123456

Validate OTP and apply electronic signature › Responses

Signature applied successfully

success

boolean · required

Indicates whether the signature was applied

Example: true

message

string · required

Confirmation message

Example: Signature completed successfully

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

signer_status

string

New signer status

Example: COMPLETED

document_status

string · enum

Overall document status after this signature

Enum values:

SIGNING

COMPLETED

Example: SIGNING

remaining_signers

integer

Number of remaining signers

Example: 1

signed_pdf_url

string | null · uri

Signed PDF URL (available only if all signers have signed)

Example: null

POST/leases/{lease_id}/signature/validate-otp

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/validate-otp \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "otp": "123456"
}
'

Example Request Body

{
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "otp": "123456"
}

application/json

Example Responses

{
  "success": true,
  "message": "Signature completed successfully. Waiting for other signers.",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signer_status": "COMPLETED",
  "document_status": "SIGNING",
  "remaining_signers": 1,
  "signed_pdf_url": null
}

application/json

Process a signature event for a lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/events/process

Processes a signature request event received from the notifier function in the context of a specific lease

Process a signature event for a lease › path Parameters

lease_id

string · uuid · required

Lease ID

Process a signature event for a lease › Request Body

Signature request event (format aligned with the notifier function)

object · required

Base event for Scaleway Topics

document_signature_id

string · uuid · required

Signature process ID

Example: 550e8400-e29b-41d4-a716-446655440000

lease_id

string · uuid · required

Lease ID

Example: 550e8400-e29b-41d4-a716-446655440001

object · required

Signer information

document_url

string · uri · required

URL of the PDF document to sign

Example: https://storage.example.com/leases/unsigned-doc.pdf

signature_url

string · uri · required

URL to access the signature

Example: https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000

expires_at

string · date-time · required

Signature request expiration date

Example: 2024-01-22T10:00:00Z

Process a signature event for a lease › Responses

Event processed successfully

status

string

event_id

string

The processed event ID

Example: evt_550e8400-e29b-41d4-a716-446655440000

document_signature_id

string · uuid

lease_id

string · uuid

signer_email

string · email

signer_type

string · enum

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

POST/leases/{lease_id}/signature/events/process

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/events/process \
  --header 'Content-Type: application/json' \
  --data '
{
  "base": {
    "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "event_type": "SignatureRequested",
    "timestamp": "2024-01-15T10:00:00Z",
    "correlation_id": "corr_550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "metadata": {}
  },
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_info": {
    "signer_type": "PROPRIETAIRE",
    "phone": "+33612345678",
    "email": "[email protected]",
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "last_name": "Dupont",
    "legal_name": "SARL Dupont Immobilier",
    "title": "M."
  },
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signature_url": "https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:00:00Z"
}
'

Example Request Body

{
  "base": {
    "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
    "event_type": "SignatureRequested",
    "timestamp": "2024-01-15T10:00:00Z",
    "correlation_id": "corr_550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "metadata": {}
  },
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_info": {
    "signer_type": "PROPRIETAIRE",
    "phone": "+33612345678",
    "email": "[email protected]",
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jean",
    "last_name": "Dupont",
    "legal_name": "SARL Dupont Immobilier",
    "title": "M."
  },
  "document_url": "https://storage.example.com/leases/unsigned-doc.pdf",
  "signature_url": "https://api.faireplace.com/api/signature/550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-22T10:00:00Z"
}

Example Responses

{
  "status": "processed",
  "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "signer_email": "[email protected]",
  "signer_type": "PROPRIETAIRE"
}

application/json

Cancel a signature request

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/signature/cancel

Cancels an ongoing signature request and resets the lease to DRAFT status. This operation allows re-initiating a signature after cancellation.

Action performed

This operation performs the following steps:

Marks the document as CANCELLED in DO Global (signature orchestrator)
Marks all signers as CANCELLED in DO Global
Marks the document as FAILED in the database (allows re-initiation)
Marks all ongoing signature requests as FAILED (Pending, OtpSent, Signing)
Resets the lease to DRAFT status

Re-initiation possible

After a cancellation, you can re-initiate a new signature via /signature/initiate. The system detects that the previous document is in FAILED status and allows re-initiation.

Difference with reset

Unlike /reset, this operation:

Preserves history: Documents and signature requests remain in the database with FAILED status
Marks as failed: The status is changed to FAILED in the DB (and CANCELLED in DO Global)
Allows auditing: Previous attempts remain visible for traceability
Allows re-initiation: A new signature process can be initiated immediately

Use cases

Use this operation when:

You have detected an error in the contract before sending
You want to correct the document and re-initiate
You need to preserve the history of attempts
The tenant is not responding and you want to re-initiate after correction

Prerequisites

The lease must be in PENDING_SIGNATURE status
A signature document must exist
The user must have the LeasesWrite permission

Cancel a signature request › path Parameters

lease_id

string · uuid · required

Lease ID

Cancel a signature request › Responses

Signature cancelled successfully

Response after cancelling a signature request. Cancellation marks the document as CANCELLED in the DO Global and sets the lease back to DRAFT status, while preserving the history of signature attempts.

success

boolean · required

Indicates whether the cancellation succeeded

Example: true

message

string · required

Confirmation message

Example: Signature cancelled for lease 550e8400-e29b-41d4-a716-446655440001

document_signature_id

string · uuid · required

Cancelled signature document ID

Example: 550e8400-e29b-41d4-a716-446655440000

DELETE/leases/{lease_id}/signature/cancel

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/cancel

Example Responses

{
  "success": true,
  "message": "Signature cancelled for lease 550e8400-e29b-41d4-a716-446655440001",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000"
}

application/json

Fully reset a signature

DELETE

https://api.faireplace.com/api

/leases/{lease_id}/signature/reset

Completely resets all signatures for a lease by deleting all traces. This operation allows starting from scratch without keeping any history.

Action performed

This operation performs the following steps:

Deletes the signature document in DO Global (signature orchestrator)
Deletes all signature requests in the database
Deletes the signature document in the database
Resets the lease to DRAFT status

Consequences

All signature data is deleted (no history retained)
The lease can be re-initiated for a new signature
Previously generated PDFs remain in the media system but are no longer linked
No trace of the previous attempt is retained

Difference with cancel

Unlike /cancel, this operation:

Completely deletes: All data is deleted (no retention)
No history: No trace of the previous attempt
Start from scratch: As if no signature was ever initiated

Use cases

Use this operation when:

The tenant is not responding after several days and you want to start from scratch
You need to completely delete an erroneous attempt
You want a new signature process without history
A major contract change requires a new document

Prerequisites

The lease must be in PENDING_SIGNATURE status
The user must have the LeasesWrite permission

Fully reset a signature › path Parameters

lease_id

string · uuid · required

Lease ID

Fully reset a signature › Responses

Signature reset successfully

Response after a complete signature reset. The complete reset deletes all signature data (documents and requests) and sets the lease back to DRAFT status, allowing a new signature initiation.

success

boolean · required

Indicates whether the reset succeeded

Example: true

message

string · required

Confirmation message

Example: Signature fully reset for lease 550e8400-e29b-41d4-a716-446655440001

DELETE/leases/{lease_id}/signature/reset

curl --request DELETE \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/reset

Example Responses

{
  "success": true,
  "message": "Signature completely reset for lease 550e8400-e29b-41d4-a716-446655440001"
}

application/json

Resend signature request for a signer

POST

https://api.faireplace.com/api

/leases/{lease_id}/signature/resend/{signer_type}

Resends the signature request for a specific signer (owner or tenant).

Action performed

This operation:

Resets the signer's status to PENDING
Resets notification counters
Sends a new INITIAL notification (SMS/Email) to the signer
Allows a new signature attempt for this signer only

Use cases

A signer did not receive the initial notification
A signer needs a new link to sign
Reset after a signature error for a single signer

Prerequisites

The lease must be in PENDING_SIGNATURE status
A signature document must exist
The specified signer must exist in the signature requests
The user must have the LeasesWrite permission

Note

This operation only affects the specified signer. Other signers retain their current status.

Resend signature request for a signer › path Parameters

lease_id

string · uuid · required

Lease ID

signer_type

string · enum · required

Signer type for which to resend the request

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

Resend signature request for a signer › Request Body optional

Resend signature request for a signer › Responses

Signature request resent successfully

Response after resending a signature request for a specific signer. Resending resets the signer's status to PENDING and resends the notifications (SMS/Email) to allow a new signature attempt.

success

boolean · required

Indicates whether the resend succeeded

Example: true

message

string · required

Confirmation message

Example: Signature request resent for signer proprietaire

signer_type

string · enum · required

Signer type

Enum values:

PROPRIETAIRE

LOCATAIRE

AGENT_IMMOBILIER

Example: PROPRIETAIRE

resend_count

integer · min: 0 · required

Total number of resends performed for this signer (including this request)

Example: 1

remaining_resends

integer · min: 0 · required

Number of remaining allowed resends (maximum 5 total)

Example: 4

POST/leases/{lease_id}/signature/resend/{signer_type}

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/signature/resend/:signer_type \
  --header 'Content-Type: application/json' \
  --data '{}'

Example Request Body

{}

Example Responses

{
  "success": true,
  "message": "Signature request resent for signer proprietaire",
  "signer_type": "PROPRIETAIRE",
  "resend_count": 1,
  "remaining_resends": 4
}

application/json

Create a payment intent for a lease

POST

https://api.faireplace.com/api

/leases/{lease_id}/payment/create-intent

Creates a payment intent for a lease (signing fees, etc.).

Supported methods:

stripe: creates a Stripe PaymentIntent; the response contains client_secret for Stripe Elements (web).
credit: debits the user's credit balance; the response may contain balance_after.

Prerequisites:

The lease must exist (otherwise 404).
LeasesWrite permission required.
For credits: sufficient balance (otherwise 422 business error).

Create a payment intent for a lease › path Parameters

lease_id

string · uuid · required

Lease ID

Create a payment intent for a lease › Request Body

Request to create a payment intent for a lease. The `lease_id` is provided in the route path, not in the body.

amount

integer · int64 · min: 1 · required

Amount in cents (e.g. 2990 = 29.90 EUR).

Example: 2990

currency

string · minLength: 1 · maxLength: 10 · required

Currency code (e.g. "eur", "EUR").

Example: eur

payment_method

string · enum · required

Payment method for a lease.

stripe: card payment via Stripe (PaymentIntent)
credit: debit from the user's credit balance

Enum values:

stripe

credit

Example: stripe

object | null

Optional metadata propagated to the payment port. The backend automatically adds lease_id and reason (e.g. "lease_payment").

Create a payment intent for a lease › Responses

Payment intent created successfully

Response after creating a payment intent. - For Stripe: contains `client_secret` for Stripe Elements. - For credits: may contain `balance_after` (balance after debit).

payment_intent_id

string · required

Stripe PaymentIntent ID (e.g. "pi_xxx") or credit transaction ID.

Example: pi_3ABC123xyz

status

string · enum · required

Payment status.

Enum values:

pending

succeeded

failed

canceled

Example: succeeded

amount

integer · int64 · required

Amount in cents.

Example: 2990

currency

string · required

payment_method

string · enum · required

Payment method for a lease.

stripe: card payment via Stripe (PaymentIntent)
credit: debit from the user's credit balance

Enum values:

stripe

credit

Example: stripe

client_secret

string | null

Client secret for Stripe Elements (web). Absent for credit payments.

Example: pi_3ABC123xyz_secret_xxx

balance_after

integer | null · int64

Credit balance after consumption (only if payment_method = credit).

Example: 4710

POST/leases/{lease_id}/payment/create-intent

curl --request POST \
  --url https://api.faireplace.com/api/leases/:lease_id/payment/create-intent \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}
'

Example Request Body

{
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}

application/json

Example Responses

{
  "payment_intent_id": "pi_3ABC123xyz",
  "client_secret": "pi_3ABC123xyz_secret_xxx",
  "status": "pending",
  "amount": 2990,
  "currency": "eur",
  "payment_method": "stripe"
}

application/json

Estates Signatures