API Overview

The Fondaro API gives you programmatic access to property listings, agents, and related resources. Use it to integrate Fondaro data into your own applications, websites, and workflows.

Base URL

All API requests are made to:

Authentication

Every request must include an API key in the Authorization header:

See the Authentication page for details on creating and managing API keys.

Response Format

All successful responses return JSON. A typical list response includes the data and a total count:

{
  "results": [ ... ],
  "total": 142
}

Single-resource responses return the object directly:

{
  "id": "a1b2c3d4-...",
  "referenceNumber": "HQL-12345",
  "listingType": "sale",
  "propertyType": "villa",
  ...
}

Error Format

Errors return an appropriate HTTP status code with a JSON body:

{
  "statusCode": 404,
  "message": "Property with ID a1b2c3d4-... not found",
  "error": "Not Found"
}

Common Status Codes

Validation Errors

When request body validation fails, the response includes details about which fields are invalid:

{
  "statusCode": 400,
  "message": [
    "Country code must be exactly 2 characters (ISO 3166-1 alpha-2)",
    "Currency must be 3 uppercase letters (e.g., EUR, USD, GBP)"
  ],
  "error": "Bad Request"
}

Pagination

List endpoints use page-based pagination with two parameters:

The response includes a total field so you can calculate the number of pages:

curl -X POST https://api.fondaro.com/properties/search \
  -H "Authorization: Bearer fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"page": 2, "limit": 10}'

{
  "results": [ ... ],
  "total": 142
}

Total pages = Math.ceil(total / limit).

Rate Limits

The API enforces rate limits per authentication token:

When you exceed a limit, the API returns 429 Too Many Requests. Back off and retry after the window resets.

Dual Authentication

All property and agent endpoints accept both JWT tokens (from the Fondaro dashboard) and API keys. This means the same endpoints power both the dashboard UI and external integrations.