Copy page

Electronic Signatures

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 API key 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 $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mr.",
    "first_name": "Jean",
    "last_name": "Dupont",
    "owner_category": "individual",
    "email": "jean.dupont@sci-rivoli.com",
    "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": "jean.dupont@sci-rivoli.com",
  "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 a country reference first.

Get a place type

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

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

Get the country

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

Select the country matching your property's jurisdiction. The country determines which rent regulation and rent control rules apply.

Create the place

Code
curl -X POST https://api.faireplace.com/api/places \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Residence Les Jardins",
    "type_id": "type-aabb1122-3344-5566-7788-99aabbccddee",
    "country_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 $API_KEY" \
  -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 $API_KEY" \
  -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 $API_KEY" \
  -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 $API_KEY" \
  -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 $API_KEY" \
  -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 $API_KEY"

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 $API_KEY" \
  -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 for the property's area (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 $API_KEY" \
  -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": "marie.martin@email.com",
    "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": "marie.martin@email.com",
  "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 $API_KEY" \
  -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 $API_KEY" \
  -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 $API_KEY" \
  -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 $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_id": "pdf-6f789012-abcd-ef12-3456-7890abcdef34",
    "signers": [
      {
        "signer_type": "PROPRIETAIRE",
        "first_name": "Jean",
        "last_name": "Dupont",
        "person_id": "550e8400-e29b-41d4-a716-446655440000",
        "email": "jean.dupont@sci-rivoli.com",
        "phone": "+33612345678"
      },
      {
        "signer_type": "LOCATAIRE",
        "first_name": "Marie",
        "last_name": "Martin",
        "person_id": "550e8400-e29b-41d4-a716-446655440001",
        "email": "marie.martin@email.com",
        "phone": "+33698765432"
      }
    ]
  }'

Code
{
  "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": "jean.dupont@sci-rivoli.com",
      "status": "PENDING",
      "expires_at": "2026-03-05T10:08:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "signer_type": "LOCATAIRE",
      "signer_email": "marie.martin@email.com",
      "status": "PENDING",
      "expires_at": "2026-03-05T10:08:00Z"
    }
  ],
  "status": "SIGNING"
}

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 $API_KEY"

Code
{
  "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": "jean.dupont@sci-rivoli.com",
      "status": "SIGNED",
      "expires_at": "2026-03-05T10:08:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "signer_type": "LOCATAIRE",
      "signer_email": "marie.martin@email.com",
      "status": "SIGNED",
      "expires_at": "2026-03-05T10:08:00Z"
    }
  ],
  "status": "COMPLETED"
}

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 code examples

Node.js

Code
const API = "https://api.faireplace.com/api";
const API_KEY = process.env.FAIREPLACE_API_KEY;

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "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: "jean.dupont@sci-rivoli.com",
      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>",
      country_id: "<country_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: "marie.martin@email.com",
      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: [
          {
            signer_type: "PROPRIETAIRE",
            first_name: "Jean",
            last_name: "Dupont",
            person_id: owner.id,
            email: "jean.dupont@sci-rivoli.com",
            phone: "+33612345678",
          },
          {
            signer_type: "LOCATAIRE",
            first_name: "Marie",
            last_name: "Martin",
            person_id: tenant.id,
            email: "marie.martin@email.com",
            phone: "+33698765432",
          },
        ],
      }),
    }
  ).then((r) => r.json());

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

createLeaseEndToEnd().catch(console.error);

Python

Code
import os
import requests

API = "https://api.faireplace.com/api"
API_KEY = os.environ["FAIREPLACE_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def create_lease_end_to_end():
    # Step 1: Create owner
    owner = requests.post(f"{API}/owners", headers=headers, json={
        "title": "Mr.",
        "first_name": "Jean",
        "last_name": "Dupont",
        "owner_category": "individual",
        "email": "jean.dupont@sci-rivoli.com",
        "mobile_phone": "+33612345678",
        "street_name": "15 rue de Rivoli",
        "postal_code": "75001",
        "city": "Paris",
        "country": "France"
    }).json()

    # Step 2: Create place
    place = requests.post(f"{API}/places", headers=headers, json={
        "name": "Residence Les Jardins",
        "type_id": "<place_type_uuid>",
        "country_id": "<country_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"
    }).json()

    # Step 3: Add apartment
    estate = requests.post(
        f"{API}/places/{place['id']}/estates",
        headers=headers,
        json={
            "estate_type_id": "<estate_type_uuid>",
            "area": 45.0,
            "number_of_room": 2,
            "floor": 3
        }
    ).json()

    # Step 6: Create lease
    lease = requests.post(f"{API}/leases", headers=headers, json={
        "estate_id": estate["id"],
        "lease_type_id": "<habitation_vide_uuid>",
        "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",
        "usage_type": "MainResidence",
        "payment_day": 5,
        "payment_terms": "InAdvance",
        "payment_method": "BankTransfer",
        "charge_settlement_mode": "Provision"
    }).json()

    # Step 7: Create and add tenant
    tenant = requests.post(f"{API}/lessees", headers=headers, json={
        "category": "individual",
        "title": "Ms.",
        "first_name": "Marie",
        "last_name": "Martin",
        "email": "marie.martin@email.com",
        "mobile_phone": "+33698765432",
        "monthly_income": 3800.00
    }).json()

    requests.post(
        f"{API}/leases/{lease['id']}/lessees",
        headers=headers,
        json={
            "lessee_id": tenant["id"],
            "role": "PrimaryTenant",
            "start_date": "2026-04-01"
        }
    )

    # Step 8: Generate PDF
    pdf = requests.post(
        f"{API}/leases/{lease['id']}/pdf",
        headers=headers,
        json={"template_type": "StandardLease", "include_tenant_info": True}
    ).json()

    # Step 9: Initiate signature
    signature = requests.post(
        f"{API}/leases/{lease['id']}/signature/initiate",
        headers=headers,
        json={
            "pdf_id": pdf["pdf_id"],
            "signers": [
                {
                    "signer_type": "PROPRIETAIRE",
                    "first_name": "Jean",
                    "last_name": "Dupont",
                    "person_id": owner["id"],
                    "email": "jean.dupont@sci-rivoli.com",
                    "phone": "+33612345678"
                },
                {
                    "signer_type": "LOCATAIRE",
                    "first_name": "Marie",
                    "last_name": "Martin",
                    "person_id": tenant["id"],
                    "email": "marie.martin@email.com",
                    "phone": "+33698765432"
                }
            ]
        }
    ).json()

    print(f"Lease created: {lease['id']}")
    print(f"Signature initiated: {signature['document_signature_id']}")
    print(f"Status: {signature['status']}")

create_lease_end_to_end()

---

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