FairePlace Property Management API

API health check endpoints

Contact management

Real estate unit (lot) management

Lease management

Electronic lease signing. These endpoints allow you to:

• Initiate a signature process for a lease
• List contracts pending signature
• Request a signature (send OTP)
• Validate an OTP and apply the signature
• Track signature status

Endpoints reserved for Cloudflare workers (signature-orchestrator, etc.). These endpoints use API key authentication (X-API-Key) instead of Bearer API keys. They allow workers to:

• Update individual signature statuses
• Finalize signature documents
• Synchronize state between workers and the database

Tenant management.

Dedicated tenant endpoints

The endpoints under /lessee/leases are specifically designed to allow tenants to:

• View their own leases
• Sign their leases electronically
• Download signed leases

These endpoints require specific permissions:

• lessee:leases:read - To view leases
• lessee:leases:sign - To sign leases
• lessee:leases:download - To download signed leases

Owner management

Building/residence management

Room management

Equipment management

Inventory management

Key management

Property, room, and equipment types

Media management (photos, PDF documents)

Country references, rent regulation checks, and rent control compliance

Lease types and their configurations

Energy performance diagnostics (DPE)

Estate diagnostic documents management (lead, asbestos, electrical, gas, risk assessment, co-ownership rules). Diagnostics are attached to a property (estate) and can be automatically linked to lease annexes via the POST /leases/{lease_id}/annexes/attach-mandatory endpoint. Only one active diagnostic per type per estate is allowed. Creating a new diagnostic of the same type automatically deactivates the previous one.

Security deposit (dépôt de garantie) management. Per Art. 22 of Loi 89-462:

• Restitution within 1 month (conformity) or 2 months (non-conformity) after lease end
• Maximum 20% retention for co-ownership charge provisions
• Late penalty: 10% of monthly rent (HC) per month of delay
• One deposit per lease (unique constraint)

Rent receipt (quittance de loyer) generation and management. Per Art. 21 of Loi 89-462, the landlord must provide a rent receipt free of charge upon tenant request. The receipt must clearly separate rent and charges.

Key features

• Generate one receipt per active tenant, applying their rent_share percentage
• Automatic PDF generation (Typst) with full legal compliance
• Full payment → "Quittance de loyer", partial payment → "Reçu de loyer"
• Itemized charge breakdown by category
• Duplicate prevention (unique constraint per tenant/period)

Meter (compteur) management for tracking consumption in properties.

Key features

• Meter CRUD: Create and manage physical meters (electricity, gas, water, heating, cooling)
• Sub-meter hierarchy: Organize meters in parent/child relationships
• Readings: Record manual, automatic, photo, or estimated readings
• Auto-consumption: Automatic consumption calculation with rollover support
• Anomaly detection: Flags consumption deviating >50% from average
• Billing integration: Link meters to leases and charges for billing

Meter types

ELECTRICITY, GAS, WATER_HOT, WATER_COLD, HEATING, COOLING

Billing types

INDIVIDUAL, COLLECTIVE, SHARED, INCLUDED

Rental charge management including freeze periods, distribution references, notifications, regulations, reviews, audit logs, and meter associations.

Key features

• Freeze Periods: Legislative freeze periods that block charge modifications (Art. 17-2 Loi 89-462)
• Distribution References: Historical reference values for distribution key calculations
• Notifications: Consumption alerts, annual review notices, regularization reminders
• Regulations: Charge adjustments due to freeze periods or legal exceptions
• Reviews: Annual charge regularization process (Art. 23 Loi 89-462)
• Audit Logs: Full traceability of charge modifications
• Meters: Physical meter associations with leases and charges

Building-related services

Credit system management. Credits allow owners to pay for platform services (e.g., lease signing) without having to enter their payment information each time.

Features

• Purchase credits via Stripe Checkout Session
• Check credit balance
• Transaction history (purchases, consumption)
• List available packages

Restrictions

• Only users with the owner role can purchase credits
• Credits are isolated by tenant (multi-tenant)

Management of regulatory and supplementary lease annexes. Annexes are the mandatory and optional documents that accompany a rental contract in compliance with French legislation (ALUR Law, Decrees 87-712/87-713, etc.).

System catalog

The platform maintains a global catalog of system annexes containing official regulatory documents. These annexes are shared across all tenants and serve as templates when attaching to a lease.

Three source categories

Source	Description	Example
STATIC_FILE	Embedded static PDF file	Information notice, Recoverable charges
GENERATED	PDF dynamically generated from lease data	Furniture inventory
USER_UPLOAD	Document manually uploaded by the user	Insurance certificate

Recommended workflow

1. Create the lease via POST /leases
2. Attach mandatory annexes via POST /leases/{id}/annexes/attach-mandatory
3. Add custom annexes via POST /leases/{id}/annexes
4. Check compliance via GET /leases/{id}/annexes/compliance
5. Download PDFs via GET /leases/{id}/annexes/{annex_id}/download

Endpoints for receiving webhooks from external services.

Stripe Webhooks

The /webhooks/stripe endpoint receives Stripe events to:

• Automatically credit accounts after successful purchase
• Log individual payments for traceability

⚠️ Security: These endpoints use signature verification instead of standard Bearer API key authentication.

Management mandates (mandats de gestion) between a principal (owner/lessee) and a mandataire: create, attach a document, activate, and revoke.

Country reference data (ISO codes, lookups).

Coupon validation and redemption (free-signature / discount codes).

Subscription plan usage and limits (consumption summary).

Lease rent revision (IRL indexation): simulate, record, list, and apply annual rent revisions on a lease.

Unauthenticated free-tool widgets (no API key) powering the SEO calculators and document generators on faireplace.com. JSON endpoints return DTOs; the /generate and /bordereau endpoints stream a PDF (application/pdf).

Public token-based guest signature flow (no login): view the session, download the PDF, request an OTP, and sign. The guest token is carried in the URL path.

Owner-claim flow: public token-based claim view, claim confirmation, and the authenticated start of an owner claim.

Ending a lease: termination record, forced termination, and effects on the property.

Notice periods and congés (notice given by either party).

État des lieux: entry and exit inspections, room by room, with the condition of each element and its electronic signature.

Documents attached to a lease.

Generation and retrieval of lease PDFs.

Document templates attached to a lease type.

Default charge configuration carried by a lease type.

Recording and reading the rent payments of a lease.

Reminders sent to the landlord at the rent due date.

Checkout sessions, payment status, and payment confirmation.

Stripe-facing endpoints (webhooks and checkout plumbing).

Documents attached to a lease amendment (avenant).

Duration changes carried by an amendment.

Rent changes carried by an amendment.

Chronological history of an amendment.

Notifications sent about an amendment.

Validation steps an amendment must clear before it takes effect.

Building management companies (syndics) and their relationship to a property.

Fund calls (appels de fonds) issued by a syndic.

Allocation of a syndic fund call across the leases of a property.