Quickstart

Copy page

Getting Started

Make your first API call in 5 minutes.

1. Get your API credentials

Contact the FairePlace team to obtain:

• A client ID and client secret for your organization
• Access to the API environment

Once you have credentials, obtain a JWT token:

Code
 
curl -X POST https://api.faireplace.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response:

Code
 
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-02-20T10:30:00Z"
}

Save the token — you'll include it in every request.

2. Verify the connection

Code
 
curl https://api.faireplace.com/api/health

Code
 
{
  "status": "ok"
}

3. Create your first property owner

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": "a1b2c3d4-e5f6-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:30:00Z"
}

4. Create a building

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": "<place_type_uuid>",
    "legislative_zone_id": "<zone_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"
  }'

Tip: Get available place types with GET /api/types/places and legislative zones with GET /api/legislative-zones.

5. Add an apartment

Code
 
curl -X POST https://api.faireplace.com/api/places/<place_uuid>/estates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "estate_type_id": "<estate_type_uuid>",
    "area": 45.0,
    "number_of_room": 2,
    "floor": 3,
    "description": "T2 with balcony, 3rd floor"
  }'

6. Create a lease

Code
 
curl -X POST https://api.faireplace.com/api/leases \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "estate_id": "<estate_uuid>",
    "lease_type_id": "<lease_type_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"
  }'

You now have a property with a lease ready for tenants and signatures.

What's next

• Add tenants and sign the lease — Complete end-to-end tutorial
• Electronic signatures — Set up OTP-based signature collection
• Payments & Credits — Purchase signature credits via Stripe
• Browse all API modules — Detailed endpoint documentation

---

API reference

Authentication

All requests (except health check) require a Bearer token:

Code
 
Authorization: Bearer <your-jwt-token>

See Authentication for details on permissions and token management.

Response format

Success:

Code
 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Residence Les Jardins",
  "created_at": "2026-02-19T10:30:00Z",
  "updated_at": "2026-02-19T10:30:00Z"
}

Error:

Code
 
{
  "error": {
    "code": 422,
    "type": "VALIDATION_ERROR",
    "message": "Rent amount must be greater than 0",
    "details": {
      "field": "rent_amount"
    }
  }
}

See Error Handling for the full error reference.

Pagination

List endpoints support pagination:

Code
 
curl "https://api.faireplace.com/api/leases?page=2&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Code
 
{
  "data": [...],
  "meta": {
    "pagination": {
      "current_page": 2,
      "per_page": 50,
      "total": 150,
      "total_pages": 3,
      "has_next": true,
      "has_prev": true
    }
  }
}

Filtering and sorting

Code
 
# Filter leases by status
curl "https://api.faireplace.com/api/leases?status=active" \
  -H "Authorization: Bearer $TOKEN"

# Sort by creation date (newest first)
curl "https://api.faireplace.com/api/leases?sort=-created_at" \
  -H "Authorization: Bearer $TOKEN"

# Search contacts
curl "https://api.faireplace.com/api/contacts?search=dupont" \
  -H "Authorization: Bearer $TOKEN"

Rate limits

• 1,000 requests per hour per tenant
• Rate limit headers in every response:
  • X-RateLimit-Limit — Maximum requests per hour
  • X-RateLimit-Remaining — Requests remaining
  • X-RateLimit-Reset — Unix timestamp when the limit resets