# 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.

1. Log in to [FairePlace](https://app.faireplace.com)
2. Go to **Paramètres** > **Développeur** > **Clés API**
3. Click **+ Créer une clé API**, name it, and click **Créer**
4. Copy the key — it starts with `fp_` and is only shown once

```bash
export API_KEY="fp_your_api_key_here"
```

> **Want to test first?** Use the [sandbox environment](/quickstart/sandbox) — no real data, no charges, OTP bypass with code `000000`.

## Step 1: Verify your connection

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

```json
{"status": "ok"}
```

If you get `401`, check your API key. See [Authentication](/quickstart/authentication) for troubleshooting.

## Step 2: Create a property owner

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

```bash
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"
  }'
```

```json
{
  "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.

```bash
# 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"
```

```bash
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"
  }'
```

```json
{
  "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.

```bash
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"
  }'
```

```json
{
  "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.

```bash
# 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)
```

```bash
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"
  }'
```

```json
{
  "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](/compliance/rent-regulation).

## Step 6: Add a tenant

Create the tenant, then link them to the lease.

```bash
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
  }'
```

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

```bash
# 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

```bash
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}'
```

```json
{
  "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"
}
```

```bash
# 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](/payments/credits).

```bash
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"
      }
    ]
  }'
```

```json
{
  "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

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

```json
{
  "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](/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](/core/errors) for the complete error reference.

---

## Complete Node.js example

```javascript
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

```python
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](/quickstart/sandbox)** — Test everything without real data
- **[Authentication](/quickstart/authentication)** — API key lifecycle, permissions, rate limits
- **[Error Handling](/core/errors)** — Handle failures gracefully
- **[API Reference](/api)** — All 370+ endpoints