Quickstart

Getting Started

Create a signed lease in 10 minutes. This guide walks you through the complete flow — from your first API call to a legally signed PDF.

Before you start

You need a FairePlace account and an API key.

Log in to FairePlace
Go to Parametres > Developpeur > Cles API
Click + Creer une cle API, name it, and click Creer
Copy the key — it starts with fp_ and is only shown once

Code
export API_KEY="fp_your_api_key_here"

Want to test first? Use the sandbox environment — no real data, no charges, OTP bypass with code 000000.

Step 1: Verify your connection

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


Code
{"status": "ok"}

If you get 401, check your API key. See Authentication for troubleshooting.

Step 2: Create a 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@example.com",
    "mobile_phone": "+33612345678",
    "street_name": "15 rue de Rivoli",
    "postal_code": "75001",
    "city": "Paris",
    "country": "France"
  }'


Code
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "first_name": "Jean",
  "last_name": "Dupont",
  "owner_category": "individual",
  "created_at": "2026-03-17T10:00:00Z"
}

Save the id — you'll need it in the next step.

Step 3: Create a building

A "place" is a building or property complex.

Code
# First, get the available place types and country reference
curl https://api.faireplace.com/api/types/places \
  -H "Authorization: Bearer $API_KEY"

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

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": "<place_type_uuid>",
    "country_id": "<country_uuid>",
    "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "address_line1": "24 rue du Faubourg Saint-Antoine",
    "postal_code": "75012",
    "city": "Paris",
    "number_of_floor": 6,
    "place_category": "Collective",
    "legal_regime": "Copropriete"
  }'


Code
{
  "id": "b2c3d4e5-f6a7-890b-cdef-1234567890ab",
  "name": "Residence Les Jardins",
  "postal_code": "75012",
  "city": "Paris",
  "created_at": "2026-03-17T10:01:00Z"
}

Step 4: Add an apartment

Estates are individual rental units within a building.

Code
curl -X POST https://api.faireplace.com/api/places/b2c3d4e5-f6a7-890b-cdef-1234567890ab/estates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "estate_type_id": "<estate_type_uuid>",
    "area": 45.0,
    "number_of_room": 2,
    "floor": 3,
    "description": "T2 lumineux avec balcon, 3e etage"
  }'


Code
{
  "id": "c3d4e5f6-a7b8-90cd-ef12-34567890abcd",
  "area": 45.0,
  "number_of_room": 2,
  "floor": 3,
  "created_at": "2026-03-17T10:02:00Z"
}

Tip: Get estate types with GET /api/types/estates.

Step 5: Create a lease

The lease ties together the estate, legal framework, and rental terms. FairePlace automatically validates rent against regulatory limits.

Code
# First, get the available lease types
curl https://api.faireplace.com/api/lease-types \
  -H "Authorization: Bearer $API_KEY"
# Use "HabitationVide" for unfurnished residential (most common)

Code
curl -X POST https://api.faireplace.com/api/leases \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "estate_id": "c3d4e5f6-a7b8-90cd-ef12-34567890abcd",
    "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"
  }'


Code
{
  "id": "d4e5f6a7-b890-cdef-1234-567890abcdef",
  "estate_id": "c3d4e5f6-a7b8-90cd-ef12-34567890abcd",
  "rent_amount": 950.00,
  "deposit_amount": 950.00,
  "status": "Draft",
  "created_at": "2026-03-17T10:03:00Z"
}

What if rent exceeds the cap? You'll get a 422 COMPLIANCE_ERROR with the maximum allowed rent per m². See Rent Regulation.

Step 6: Add a tenant

Create the tenant, then link them to the lease.

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",
    "monthly_income": 3800.00
  }'


Code
{
  "id": "e5f6a7b8-90cd-ef12-3456-7890abcdef12",
  "first_name": "Marie",
  "last_name": "Martin",
  "created_at": "2026-03-17T10:04:00Z"
}

Code
# Link the tenant to the lease
curl -X POST https://api.faireplace.com/api/leases/d4e5f6a7-b890-cdef-1234-567890abcdef/lessees \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lessee_id": "e5f6a7b8-90cd-ef12-3456-7890abcdef12",
    "role": "PrimaryTenant",
    "start_date": "2026-04-01"
  }'

Step 7: Generate the lease PDF

Code
curl -X POST https://api.faireplace.com/api/leases/d4e5f6a7-b890-cdef-1234-567890abcdef/pdf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_type": "StandardLease", "include_tenant_info": true}'


Code
{
  "pdf_id": "f6a7b890-cdef-1234-5678-90abcdef1234",
  "status": "Generated",
  "download_url": "/api/leases/pdf/f6a7b890-cdef-1234-5678-90abcdef1234",
  "pages": 12,
  "created_at": "2026-03-17T10:05:00Z"
}

Code
# Download and review
curl https://api.faireplace.com/api/leases/pdf/f6a7b890-cdef-1234-5678-90abcdef1234 \
  -H "Authorization: Bearer $API_KEY" \
  -o lease-2026-001.pdf

Step 8: Collect signatures

Initiate eIDAS-compliant electronic signatures. Each signer receives an OTP via SMS.

Prerequisite: You need at least 1 signature credit. See Payments & Credits.

Code
curl -X POST https://api.faireplace.com/api/leases/d4e5f6a7-b890-cdef-1234-567890abcdef/signature/initiate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_id": "f6a7b890-cdef-1234-5678-90abcdef1234",
    "signers": [
      {
        "signer_type": "PROPRIETAIRE",
        "first_name": "Jean",
        "last_name": "Dupont",
        "person_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "email": "jean.dupont@example.com",
        "phone": "+33612345678"
      },
      {
        "signer_type": "LOCATAIRE",
        "first_name": "Marie",
        "last_name": "Martin",
        "person_id": "e5f6a7b8-90cd-ef12-3456-7890abcdef12",
        "email": "marie.martin@email.com",
        "phone": "+33698765432"
      }
    ]
  }'


Code
{
  "document_signature_id": "a7b890cd-ef12-3456-7890-abcdef123456",
  "status": "SIGNING",
  "signature_requests": [
    {"signer_type": "PROPRIETAIRE", "status": "PENDING", "expires_at": "2026-03-31T10:06:00Z"},
    {"signer_type": "LOCATAIRE", "status": "PENDING", "expires_at": "2026-03-31T10:06:00Z"}
  ]
}

The owner receives an SMS with a 6-digit OTP. After validating and signing, the tenant is notified next.

Step 9: Check signature status

Code
curl https://api.faireplace.com/api/leases/d4e5f6a7-b890-cdef-1234-567890abcdef/signature/status \
  -H "Authorization: Bearer $API_KEY"


Code
{
  "status": "COMPLETED",
  "signature_requests": [
    {"signer_type": "PROPRIETAIRE", "status": "SIGNED"},
    {"signer_type": "LOCATAIRE", "status": "SIGNED"}
  ]
}

When status is COMPLETED:

The signed PDF is available for download
An eIDAS-compliant proof certificate is generated
The lease status changes to Active

You just created a legally signed lease through the API.

What can go wrong

Situation	Error	What to do
Rent exceeds legal cap	`422 COMPLIANCE_ERROR`	Lower rent or add a justified `rent_supplement`
Deposit too high	`422 COMPLIANCE_ERROR`	Max 1 month rent (unfurnished) or 2 months (furnished)
No signature credits	`402 PAYMENT_REQUIRED`	Buy credits at Payments & Credits
OTP expired	`422 OTP_EXPIRED`	Resend with `POST /leases/{id}/signature/resend/{signer_type}`
Signer wrong OTP 3x	`429 OTP_LOCKED`	Wait 5 minutes, then resend a new OTP
API key expired	`401 UNAUTHORIZED`	Create a new key in the dashboard
Rate limited	`429 RATE_LIMITED`	Wait for `Retry-After` header, use exponential backoff
Resource from other tenant	`404 NOT_FOUND`	Check you're using IDs from your own organization

See Error Handling for the complete error reference.

Complete Node.js example


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 post(path, body) {
  const res = await fetch(`${API}${path}`, {
    method: "POST", headers, body: JSON.stringify(body),
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`${res.status}: ${err.error?.message || "Unknown error"}`);
  }
  return res.json();
}

async function get(path) {
  const res = await fetch(`${API}${path}`, { headers });
  if (!res.ok) throw new Error(`${res.status}`);
  return res.json();
}

async function createSignedLease() {
  // 1. Owner
  const owner = await post("/owners", {
    first_name: "Jean", last_name: "Dupont",
    owner_category: "individual",
    email: "jean@example.com", mobile_phone: "+33612345678",
  });

  // 2. Building + apartment
  const place = await post("/places", {
    name: "Residence Les Jardins", owner_id: owner.id,
    type_id: "<place_type_uuid>", country_id: "<country_uuid>",
    postal_code: "75012", city: "Paris",
  });
  const estate = await post(`/places/${place.id}/estates`, {
    estate_type_id: "<estate_type_uuid>", area: 45.0, number_of_room: 2,
  });

  // 3. Lease
  const lease = await post("/leases", {
    estate_id: estate.id, lease_type_id: "<habitation_vide_uuid>",
    start_date: "2026-04-01", end_date: "2029-03-31",
    rent_amount: 950, deposit_amount: 950,
    rent_frequency: "Monthly", revision_index_type: "IRL",
    usage_type: "MainResidence", payment_day: 5,
    payment_terms: "InAdvance", payment_method: "BankTransfer",
    charge_settlement_mode: "Provision",
  });

  // 4. Tenant
  const tenant = await post("/lessees", {
    category: "individual", first_name: "Marie", last_name: "Martin",
    email: "marie@email.com", mobile_phone: "+33698765432",
  });
  await post(`/leases/${lease.id}/lessees`, {
    lessee_id: tenant.id, role: "PrimaryTenant", start_date: "2026-04-01",
  });

  // 5. PDF
  const pdf = await post(`/leases/${lease.id}/pdf`, {
    template_type: "StandardLease", include_tenant_info: true,
  });

  // 6. Signature
  const sig = await post(`/leases/${lease.id}/signature/initiate`, {
    pdf_id: pdf.pdf_id,
    signers: [
      { signer_type: "PROPRIETAIRE", first_name: "Jean", last_name: "Dupont",
        person_id: owner.id, email: "jean@example.com", phone: "+33612345678" },
      { signer_type: "LOCATAIRE", first_name: "Marie", last_name: "Martin",
        person_id: tenant.id, email: "marie@email.com", phone: "+33698765432" },
    ],
  });

  console.log(`Lease ${lease.id} — signature status: ${sig.status}`);
}

createSignedLease().catch(console.error);

Complete Python example


Code
import os, 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 post(path, body):
    r = requests.post(f"{API}{path}", headers=headers, json=body)
    r.raise_for_status()
    return r.json()

def get(path):
    r = requests.get(f"{API}{path}", headers=headers)
    r.raise_for_status()
    return r.json()

# 1. Owner
owner = post("/owners", {
    "first_name": "Jean", "last_name": "Dupont",
    "owner_category": "individual",
    "email": "jean@example.com", "mobile_phone": "+33612345678",
})

# 2. Building + apartment
place = post("/places", {
    "name": "Residence Les Jardins", "owner_id": owner["id"],
    "type_id": "<place_type_uuid>", "country_id": "<country_uuid>",
    "postal_code": "75012", "city": "Paris",
})
estate = post(f"/places/{place['id']}/estates", {
    "estate_type_id": "<estate_type_uuid>", "area": 45.0, "number_of_room": 2,
})

# 3. Lease
lease = post("/leases", {
    "estate_id": estate["id"], "lease_type_id": "<habitation_vide_uuid>",
    "start_date": "2026-04-01", "end_date": "2029-03-31",
    "rent_amount": 950, "deposit_amount": 950,
    "rent_frequency": "Monthly", "revision_index_type": "IRL",
    "usage_type": "MainResidence", "payment_day": 5,
    "payment_terms": "InAdvance", "payment_method": "BankTransfer",
    "charge_settlement_mode": "Provision",
})

# 4. Tenant
tenant = post("/lessees", {
    "category": "individual", "first_name": "Marie", "last_name": "Martin",
    "email": "marie@email.com", "mobile_phone": "+33698765432",
})
post(f"/leases/{lease['id']}/lessees", {
    "lessee_id": tenant["id"], "role": "PrimaryTenant", "start_date": "2026-04-01",
})

# 5. PDF
pdf = post(f"/leases/{lease['id']}/pdf", {
    "template_type": "StandardLease", "include_tenant_info": True,
})

# 6. Signature
sig = post(f"/leases/{lease['id']}/signature/initiate", {
    "pdf_id": pdf["pdf_id"],
    "signers": [
        {"signer_type": "PROPRIETAIRE", "first_name": "Jean", "last_name": "Dupont",
         "person_id": owner["id"], "email": "jean@example.com", "phone": "+33612345678"},
        {"signer_type": "LOCATAIRE", "first_name": "Marie", "last_name": "Martin",
         "person_id": tenant["id"], "email": "marie@email.com", "phone": "+33698765432"},
    ],
})

print(f"Lease {lease['id']} — signature status: {sig['status']}")

Next steps

Sandbox — Test everything without real data
Authentication — API key lifecycle, permissions, rate limits
Error Handling — Handle failures gracefully
API Reference — All 370+ endpoints

Last modified on March 17, 2026

FairePlace API Authentication