Core Concepts

Copy page

Pagination, Filtering & Sorting

All list endpoints in the FairePlace API support pagination, filtering, and sorting with a consistent interface.

Pagination

Request parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
per_page	integer	20	Items per page (max 100)

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

Response format

Every paginated response includes a meta.pagination object:

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

Field	Description
current_page	The current page number
per_page	Number of items per page
total	Total number of items across all pages
total_pages	Total number of pages
has_next	Whether there are more pages after this one
has_prev	Whether there are pages before this one

Iterating through all pages

Code
 
async function fetchAll(endpoint) {
  let page = 1;
  let allData = [];

  while (true) {
    const response = await fetch(
      `https://api.faireplace.com/api/${endpoint}?page=${page}&per_page=100`,
      { headers: { Authorization: `Bearer ${TOKEN}` } }
    );
    const result = await response.json();
    allData.push(...result.data);

    if (!result.meta.pagination.has_next) break;
    page++;
  }

  return allData;
}

Filtering

Filter results using query parameters. Available filters vary by resource.

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

# Filter estates by minimum area
curl "https://api.faireplace.com/api/places/{place_id}/estates?area_min=30" \
  -H "Authorization: Bearer $TOKEN"

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

Common filters

Resource	Filters
Leases	status, estate_id, start_date_from, start_date_to
Places	owner_id, postal_code, city, place_category
Estates	area_min, area_max, floor, number_of_room
Lessees	search, category
Owners	search, owner_category
Contacts	search, type

Date range filtering

Use _from and _to suffixes for date ranges:

Code
 
# Leases starting in 2026
curl "https://api.faireplace.com/api/leases?start_date_from=2026-01-01&start_date_to=2026-12-31" \
  -H "Authorization: Bearer $TOKEN"

Sorting

Sort results using the sort parameter. Prefix with - for descending order.

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

# Sort by rent amount (lowest first)
curl "https://api.faireplace.com/api/leases?sort=rent_amount" \
  -H "Authorization: Bearer $TOKEN"

# Sort by last name (alphabetical)
curl "https://api.faireplace.com/api/lessees?sort=last_name" \
  -H "Authorization: Bearer $TOKEN"

Sortable fields

Most resources support sorting on:

• created_at / -created_at
• updated_at / -updated_at
• Resource-specific fields (e.g., rent_amount, last_name, area)

Combining parameters

Pagination, filtering, and sorting can be combined:

Code
 
# Active leases, sorted by rent (highest first), page 1 of 20
curl "https://api.faireplace.com/api/leases?status=Active&sort=-rent_amount&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Rate limits

List endpoints are subject to the standard rate limit of 1,000 requests per hour per tenant. Large per_page values do not count as multiple requests.

Rate limit headers are included in every response:

Header	Description
X-RateLimit-Limit	Maximum requests per hour
X-RateLimit-Remaining	Requests remaining in the window
X-RateLimit-Reset	Unix timestamp when the limit resets

---

Related

• Error Handling — Error codes and troubleshooting
• Authentication — JWT tokens and permissions
• Multi-tenancy — Data isolation