Electronic Signatures

Copy page

Create a Lease End-to-End

The complete workflow from an empty account to a signed lease agreement.

This tutorial walks you through every step: creating the property owner, setting up the building and apartment, configuring the lease, adding tenants, generating the PDF, and collecting electronic signatures.

Overview

Code
 
Step 1: Create owner          POST /api/owners
Step 2: Create building        POST /api/places
Step 3: Add apartment          POST /api/places/{id}/estates
Step 4: Set up rooms           POST /api/places/{id}/estates/{id}/rooms
Step 5: Choose lease type      GET  /api/lease-types
Step 6: Create the lease       POST /api/leases
Step 7: Add the tenant         POST /api/leases/{id}/lessees
Step 8: Generate the PDF       POST /api/leases/{id}/pdf
Step 9: Initiate signature     POST /api/leases/{id}/signature/initiate
Step 10: Check status          GET  /api/leases/{id}/signature/status

Prerequisites: You need a valid JWT token with properties:write, leases:write, lessees:write, and signatures:write permissions. See Authentication.

All examples below use consistent UUIDs so you can follow the data flow across steps.

---

Step 1: Create the property owner

Every property needs an owner. This can be an individual or a company (SCI).

Code
 
curl -X POST https://api.faireplace.com/api/owners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mr.",
    "first_name": "Jean",
    "last_name": "Dupont",
    "owner_category": "individual",
    "email": "[email protected]",
    "mobile_phone": "+33612345678",
    "street_name": "15 rue de Rivoli",
    "postal_code": "75001",
    "city": "Paris",
    "country": "France"
  }'

Code
 
{
  "id": "owner-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "title": "Mr.",
  "first_name": "Jean",
  "last_name": "Dupont",
  "owner_category": "individual",
  "email": "[email protected]",
  "mobile_phone": "+33612345678",
  "created_at": "2026-02-19T10:00:00Z"
}

For a company owner (SCI): Set owner_category to "company" and add legal_name, siret, and rcs_city fields.

---

Step 2: Create the building

A place represents a building or property complex. You need a place type and legislative zone first.

Get a place type

Code
 
curl https://api.faireplace.com/api/types/places \
  -H "Authorization: Bearer $TOKEN"

Pick the appropriate type (e.g., Immeuble for apartment building). Note the id.

Get the legislative zone

Code
 
curl https://api.faireplace.com/api/legislative-zones \
  -H "Authorization: Bearer $TOKEN"

Select the zone matching your property's location. Legislative zones determine rent control rules.

Create the place

Code
 
curl -X POST https://api.faireplace.com/api/places \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Residence Les Jardins",
    "type_id": "type-aabb1122-3344-5566-7788-99aabbccddee",
    "legislative_zone_id": "zone-1122aabb-3344-5566-7788-99aabbccddee",
    "owner_id": "owner-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "address_line1": "24 rue du Faubourg Saint-Antoine",
    "postal_code": "75012",
    "city": "Paris",
    "latitude": 48.8503,
    "longitude": 2.3714,
    "number_of_floor": 6,
    "place_category": "Collective",
    "legal_regime": "Copropriete",
    "digicode": "A1234B",
    "construction_date": "1975-01-01T00:00:00"
  }'

Code
 
{
  "id": "place-2b3c4d5e-6f78-90ab-cdef-1234567890ab",
  "name": "Residence Les Jardins",
  "address_line1": "24 rue du Faubourg Saint-Antoine",
  "postal_code": "75012",
  "city": "Paris",
  "place_category": "Collective",
  "legal_regime": "Copropriete",
  "created_at": "2026-02-19T10:01:00Z"
}

---

Step 3: Add the apartment

Estates are individual rental units within a place (apartments, studios, etc.).

Code
 
curl -X POST https://api.faireplace.com/api/places/place-2b3c4d5e-6f78-90ab-cdef-1234567890ab/estates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "estate_type_id": "etype-ccdd1122-3344-5566-7788-99aabbccddee",
    "area": 45.0,
    "number_of_room": 2,
    "floor": 3,
    "description": "T2 lumineux avec balcon, 3e etage, vue cour"
  }'

Code
 
{
  "id": "estate-3c4d5e6f-7890-abcd-ef12-34567890abcd",
  "place_id": "place-2b3c4d5e-6f78-90ab-cdef-1234567890ab",
  "area": 45.0,
  "number_of_room": 2,
  "floor": 3,
  "created_at": "2026-02-19T10:02:00Z"
}

Tip: Get estate types with GET /api/types/estates. Common types: Appartement, Studio, Maison, Local commercial.

---

Step 4: Set up rooms

Rooms describe the interior layout. This information appears on the lease document.

Code
 
# Living room
curl -X POST https://api.faireplace.com/api/places/place-2b3c4d5e-6f78-90ab-cdef-1234567890ab/estates/estate-3c4d5e6f-7890-abcd-ef12-34567890abcd/rooms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"room_type_id": "<room_type_uuid>", "area": 18.5, "name": "Sejour"}'

# Bedroom
curl -X POST https://api.faireplace.com/api/places/place-2b3c4d5e-6f78-90ab-cdef-1234567890ab/estates/estate-3c4d5e6f-7890-abcd-ef12-34567890abcd/rooms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"room_type_id": "<room_type_uuid>", "area": 12.0, "name": "Chambre"}'

# Kitchen
curl -X POST https://api.faireplace.com/api/places/place-2b3c4d5e-6f78-90ab-cdef-1234567890ab/estates/estate-3c4d5e6f-7890-abcd-ef12-34567890abcd/rooms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"room_type_id": "<room_type_uuid>", "area": 8.0, "name": "Cuisine"}'

# Bathroom
curl -X POST https://api.faireplace.com/api/places/place-2b3c4d5e-6f78-90ab-cdef-1234567890ab/estates/estate-3c4d5e6f-7890-abcd-ef12-34567890abcd/rooms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"room_type_id": "<room_type_uuid>", "area": 4.5, "name": "Salle de bain"}'

Tip: Get room types with GET /api/types/rooms.

---

Step 5: Choose the lease type

Lease types define the legal framework for the rental agreement.

Code
 
curl https://api.faireplace.com/api/lease-types \
  -H "Authorization: Bearer $TOKEN"

Common lease types:

Type	Description
HabitationVide	Unfurnished residential (3-year term, Loi du 6 juillet 1989)
HabitationMeublee	Furnished residential (1-year term)
MobiliteEtudiante	Student mobility lease (1-10 months)
Commercial	Commercial lease (3/6/9 years)
Professionnel	Professional use lease

For this tutorial, we'll use HabitationVide (unfurnished residential), the most common type.

---

Step 6: Create the lease

This is the main step. The lease ties together the estate, lease type, and rental terms.

Code
 
curl -X POST https://api.faireplace.com/api/leases \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "estate_id": "estate-3c4d5e6f-7890-abcd-ef12-34567890abcd",
    "lease_type_id": "<habitation_vide_uuid>",
    "reference_number": "BAIL-2026-001",
    "start_date": "2026-04-01",
    "end_date": "2029-03-31",
    "rent_amount": 950.00,
    "rent_frequency": "Monthly",
    "deposit_amount": 950.00,
    "revision_index_type": "IRL",
    "next_revision_date": "2027-04-01",
    "inventory_type": "EntryExitInventory",
    "usage_type": "MainResidence",
    "payment_day": 5,
    "payment_terms": "InAdvance",
    "payment_method": "BankTransfer",
    "charge_settlement_mode": "Provision",
    "is_subject_to_rent_evolution_decree": true,
    "is_subject_to_reference_rent_cap": true,
    "reference_rent_per_m2": 25.50,
    "reference_rent_increased_per_m2": 28.00,
    "base_rent_amount": 950.00,
    "special_conditions": "Animaux domestiques acceptes avec depot de garantie supplementaire"
  }'

Code
 
{
  "id": "lease-4d5e6f78-90ab-cdef-1234-567890abcdef",
  "estate_id": "estate-3c4d5e6f-7890-abcd-ef12-34567890abcd",
  "reference_number": "BAIL-2026-001",
  "start_date": "2026-04-01",
  "end_date": "2029-03-31",
  "rent_amount": 950.00,
  "deposit_amount": 950.00,
  "status": "Draft",
  "created_at": "2026-02-19T10:05:00Z"
}

Key fields explained:

Field	Description
rent_amount	Monthly rent excluding charges (loyer hors charges)
deposit_amount	Security deposit. Max 1 month rent for unfurnished, 2 months for furnished
revision_index_type	IRL for residential. Determines how rent is revised annually
reference_rent_per_m2	Reference rent from the legislative zone (loyer de reference)
reference_rent_increased_per_m2	Increased reference rent (loyer de reference majore)
base_rent_amount	Base rent before any complement (loyer de base)
charge_settlement_mode	Provision = estimated charges with annual settlement; Forfeit = fixed amount

---

Step 7: Add the tenant

Create the tenant first, then associate them with the lease.

Create the tenant

Code
 
curl -X POST https://api.faireplace.com/api/lessees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "individual",
    "title": "Ms.",
    "first_name": "Marie",
    "last_name": "Martin",
    "birth_date": "1992-05-14",
    "birth_place": "Lyon, France",
    "email": "[email protected]",
    "mobile_phone": "+33698765432",
    "address_street": "8 rue de la Roquette",
    "address_postal_code": "75011",
    "address_city": "Paris",
    "address_country": "France",
    "profession": "Ingenieure informatique",
    "employer_name": "Tech Solutions SA",
    "employer_phone": "+33145678901",
    "monthly_income": 3800.00,
    "bank_name": "Credit Agricole",
    "iban": "FR1420041010050500013M02606",
    "bic": "AGRIFRPP"
  }'

Code
 
{
  "id": "lessee-5e6f7890-abcd-ef12-3456-7890abcdef12",
  "category": "individual",
  "first_name": "Marie",
  "last_name": "Martin",
  "email": "[email protected]",
  "created_at": "2026-02-19T10:06:00Z"
}

Add the tenant to the lease

Code
 
curl -X POST https://api.faireplace.com/api/leases/lease-4d5e6f78-90ab-cdef-1234-567890abcdef/lessees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lessee_id": "lessee-5e6f7890-abcd-ef12-3456-7890abcdef12",
    "role": "PrimaryTenant",
    "start_date": "2026-04-01"
  }'

Adding a guarantor: Create another lessee with "category": "guarantor", then add them to the lease with "role": "Guarantor".

---

Step 8: Generate the PDF

Generate the formatted lease document ready for signature.

Code
 
curl -X POST https://api.faireplace.com/api/leases/lease-4d5e6f78-90ab-cdef-1234-567890abcdef/pdf \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_type": "StandardLease",
    "include_amendments": false,
    "include_tenant_info": true
  }'

Code
 
{
  "pdf_id": "pdf-6f789012-abcd-ef12-3456-7890abcdef34",
  "status": "Generated",
  "download_url": "/api/leases/pdf/pdf-6f789012-abcd-ef12-3456-7890abcdef34",
  "pages": 12,
  "created_at": "2026-02-19T10:07:00Z"
}

You can download the PDF to review it before sending for signature:

Code
 
curl https://api.faireplace.com/api/leases/pdf/pdf-6f789012-abcd-ef12-3456-7890abcdef34 \
  -H "Authorization: Bearer $TOKEN" \
  -o lease-bail-2026-001.pdf

---

Step 9: Initiate electronic signature

Start the signature collection process. Each signer will receive an OTP via SMS.

Important: You need signature credits. See Payments & Credits to purchase credits.

Code
 
curl -X POST https://api.faireplace.com/api/leases/lease-4d5e6f78-90ab-cdef-1234-567890abcdef/signature/initiate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_id": "pdf-6f789012-abcd-ef12-3456-7890abcdef34",
    "signers": [
      {
        "type": "Proprietaire",
        "name": "Jean Dupont",
        "email": "[email protected]",
        "phone": "+33612345678"
      },
      {
        "type": "Locataire",
        "name": "Marie Martin",
        "email": "[email protected]",
        "phone": "+33698765432"
      }
    ]
  }'

Code
 
{
  "signature_id": "sig-78901234-abcd-ef12-3456-7890abcdef56",
  "status": "Pending",
  "signers": [
    {
      "type": "Proprietaire",
      "name": "Jean Dupont",
      "status": "Pending"
    },
    {
      "type": "Locataire",
      "name": "Marie Martin",
      "status": "Pending"
    }
  ],
  "created_at": "2026-02-19T10:08:00Z"
}

Each signer will receive an SMS with an OTP code. They validate the OTP and draw their signature on the document. See Electronic Signatures for the full signature flow.

---

Step 10: Check signature status

Monitor the signature progress:

Code
 
curl https://api.faireplace.com/api/leases/lease-4d5e6f78-90ab-cdef-1234-567890abcdef/signature/status \
  -H "Authorization: Bearer $TOKEN"

Code
 
{
  "signature_id": "sig-78901234-abcd-ef12-3456-7890abcdef56",
  "status": "Completed",
  "signers": [
    {
      "type": "Proprietaire",
      "name": "Jean Dupont",
      "status": "Completed",
      "signed_at": "2026-02-19T14:30:00Z"
    },
    {
      "type": "Locataire",
      "name": "Marie Martin",
      "status": "Completed",
      "signed_at": "2026-02-19T16:45:00Z"
    }
  ],
  "signed_pdf_url": "/api/leases/lease-4d5e6f78-90ab-cdef-1234-567890abcdef/signature/document",
  "proof_url": "/api/leases/lease-4d5e6f78-90ab-cdef-1234-567890abcdef/signature/proof",
  "completed_at": "2026-02-19T16:45:00Z"
}

Once all signers have completed:

• The signed PDF is available at the signed_pdf_url
• The eIDAS-compliant proof certificate is available at the proof_url
• The lease status automatically changes to Active

---

Complete Node.js example

Code
 
const API = "https://api.faireplace.com/api";
const TOKEN = "your-jwt-token";

const headers = {
  Authorization: `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};

async function createLeaseEndToEnd() {
  // Step 1: Create owner
  const owner = await fetch(`${API}/owners`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      title: "Mr.",
      first_name: "Jean",
      last_name: "Dupont",
      owner_category: "individual",
      email: "[email protected]",
      mobile_phone: "+33612345678",
      street_name: "15 rue de Rivoli",
      postal_code: "75001",
      city: "Paris",
      country: "France",
    }),
  }).then((r) => r.json());

  // Step 2: Create place
  const place = await fetch(`${API}/places`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      name: "Residence Les Jardins",
      type_id: "<place_type_uuid>",
      legislative_zone_id: "<zone_uuid>",
      owner_id: owner.id,
      address_line1: "24 rue du Faubourg Saint-Antoine",
      postal_code: "75012",
      city: "Paris",
      number_of_floor: 6,
      place_category: "Collective",
      legal_regime: "Copropriete",
    }),
  }).then((r) => r.json());

  // Step 3: Add apartment
  const estate = await fetch(`${API}/places/${place.id}/estates`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      estate_type_id: "<estate_type_uuid>",
      area: 45.0,
      number_of_room: 2,
      floor: 3,
    }),
  }).then((r) => r.json());

  // Step 6: Create lease
  const lease = await fetch(`${API}/leases`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      estate_id: estate.id,
      lease_type_id: "<habitation_vide_uuid>",
      start_date: "2026-04-01",
      end_date: "2029-03-31",
      rent_amount: 950.0,
      rent_frequency: "Monthly",
      deposit_amount: 950.0,
      revision_index_type: "IRL",
      usage_type: "MainResidence",
      payment_day: 5,
      payment_terms: "InAdvance",
      payment_method: "BankTransfer",
      charge_settlement_mode: "Provision",
    }),
  }).then((r) => r.json());

  // Step 7: Create and add tenant
  const tenant = await fetch(`${API}/lessees`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      category: "individual",
      title: "Ms.",
      first_name: "Marie",
      last_name: "Martin",
      email: "[email protected]",
      mobile_phone: "+33698765432",
      monthly_income: 3800.0,
    }),
  }).then((r) => r.json());

  await fetch(`${API}/leases/${lease.id}/lessees`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      lessee_id: tenant.id,
      role: "PrimaryTenant",
      start_date: "2026-04-01",
    }),
  });

  // Step 8: Generate PDF
  const pdf = await fetch(`${API}/leases/${lease.id}/pdf`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      template_type: "StandardLease",
      include_tenant_info: true,
    }),
  }).then((r) => r.json());

  // Step 9: Initiate signature
  const signature = await fetch(
    `${API}/leases/${lease.id}/signature/initiate`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({
        pdf_id: pdf.pdf_id,
        signers: [
          {
            type: "Proprietaire",
            name: "Jean Dupont",
            email: "[email protected]",
            phone: "+33612345678",
          },
          {
            type: "Locataire",
            name: "Marie Martin",
            email: "[email protected]",
            phone: "+33698765432",
          },
        ],
      }),
    }
  ).then((r) => r.json());

  console.log("Lease created:", lease.id);
  console.log("Signature initiated:", signature.signature_id);
  console.log("Status:", signature.status);
}

createLeaseEndToEnd().catch(console.error);

---

What's next

• Electronic Signatures — Understand the full OTP and eIDAS workflow
• Payments & Credits — Purchase signature credits
• Leases API — Full lease endpoint reference
• Error Handling — Handle validation and compliance errors