# API overview

> Make your first Fondaro API call with an API key that acts as you, and see which credential and which page covers each part of the API.

The Fondaro API lets your own code do what you do in Fondaro: work your leads, tasks, deals and notes, search and show listings, and send brochures and documents. One API key acts as the person who made it, with the access that person has. This page gets you to a first call and shows where each area lives.

## Find the base URL

```
https://api.fondaro.com
```

Every path in these docs is relative to it. Requests and responses are JSON over HTTPS unless a page says otherwise (file uploads use `multipart/form-data`). The API is for servers: call it from your backend, an automation or a script, not from a web page.

## Make your first call

1. Create a key on the API keys page (**Settings › Integrations › For developers › API keys**). See [API keys](https://www.fondaro.com/docs/dashboard/api-keys.md). Copy it when it is shown: you see it once.
2. Save it as an environment variable:

```bash
export FONDARO_API_KEY="fondaro_pk_..."
```

3. Ask the API who the key acts as:

```bash
curl https://api.fondaro.com/v1/me \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

```json
{
  "user": { "id": "user_2abcDEF", "name": "Maria Lopez", "email": "maria@youragency.com" },
  "organization": { "id": "b7c1e0a2-1d4f-4e55-9a31-0c2f8d6e7a10", "name": "Your Agency" },
  "role": "member",
  "entitled": true,
  "key": {
    "id": "a1b2c3d4-5678-4abc-9def-123456789abc",
    "name": "Reporting script",
    "prefixHint": "fondaro_pk_Q",
    "scopes": ["crm:read"],
    "expiresAt": "2027-01-02T12:00:00.000Z"
  }
}
```

`GET /v1/me` needs no scope: any valid key with an owner can say who it is.

4. List your five newest leads (needs `crm:read`):

```bash
curl "https://api.fondaro.com/v1/leads?limit=5" \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

5. Create a lead (needs `crm:write`). Send an `Idempotency-Key` so a retry never creates a second lead:

```bash
curl -X POST https://api.fondaro.com/v1/leads \
  -H "Authorization: Bearer $FONDARO_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-0a4b-4c5d-8e9f-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Anna",
    "lastName": "Berg",
    "email": "anna@example.com",
    "phoneNumber": "+46701234567",
    "crmStatus": "lead"
  }'
```

Every `/v1` response carries an `X-Request-Id` header. Quote it if you contact support. See [Errors and limits](https://www.fondaro.com/docs/api/errors-and-limits.md).

## Choose a credential

Each part of the API takes its own credential. [Authentication](https://www.fondaro.com/docs/api/authentication.md) explains how to get and manage each one.

| You want to | Credential | Header |
|-------------|-----------|--------|
| Use the Fondaro API: CRM, listings, property search, brochures, documents | API key (`fondaro_pk_…`), acts as you | `Authorization: Bearer <key>` |
| Automate with n8n or Zapier (agency-wide, webhooks) | Integration key (`fdr_n8n_…`) | `Authorization: Bearer <key>` |
| Connect an AI client | MCP key (`fdr_mcp_…`) or browser sign-in | See [MCP server](https://www.fondaro.com/docs/api/mcp.md) |
| Call the routes the dashboard uses, as a signed-in member | Session token | `Authorization: Bearer <session-token>` |

## Find the area you need

| Area | Where | Scope |
|------|-------|-------|
| Leads, people, notes, tasks, calendar, deals, calls and emails | [Leads](https://www.fondaro.com/docs/api/v1/leads.md), [People](https://www.fondaro.com/docs/api/v1/people.md), [Notes](https://www.fondaro.com/docs/api/v1/notes.md), [Tasks and calendar](https://www.fondaro.com/docs/api/v1/tasks-and-calendar.md), [Deals](https://www.fondaro.com/docs/api/v1/deals.md), [Calls and conversations](https://www.fondaro.com/docs/api/v1/calls-and-conversations.md) | `crm:read`, `crm:write` |
| Semantic search of your CRM and listing matches | [Search](https://www.fondaro.com/docs/api/v1/search.md) | `crm:read` |
| Viewings, open houses, collections and buyer requests | [Viewings and open houses](https://www.fondaro.com/docs/api/v1/viewings-and-open-houses.md), [Network](https://www.fondaro.com/docs/api/v1/network.md) | `properties:read` |
| Listings: search, create and update | [Search](https://www.fondaro.com/docs/api/properties/search.md), [Create and update listings](https://www.fondaro.com/docs/api/properties/crud.md) | `properties:read`, `properties:write`, `media:write` |
| Property search across your connected sources | [Property sources](https://www.fondaro.com/docs/api/properties/sources.md) | `sources:read` |
| Brochures | [Brochures](https://www.fondaro.com/docs/api/v1/brochures.md) | `brochures:read`, `brochures:write` (creating a brochure, adding or refreshing listings and renewing also need `properties:read`) |
| Documents | [Documents](https://www.fondaro.com/docs/api/v1/documents.md) (an active plan is required) | `documents:read`, `documents:write` |
| Agency-wide automation and webhooks | [Integration reporting](https://www.fondaro.com/docs/api/integrations.md) | Integration key |
| AI clients | [MCP server](https://www.fondaro.com/docs/api/mcp.md), [Build with AI](https://www.fondaro.com/docs/api/ai-builders.md) | MCP key or sign-in |
| Dashboard features | [Setup](https://www.fondaro.com/docs/api/setup.md), [Inbox](https://www.fondaro.com/docs/api/inbox.md), [Calling](https://www.fondaro.com/docs/api/calling.md), [Calendar](https://www.fondaro.com/docs/api/calendar.md), [Teams](https://www.fondaro.com/docs/api/teams.md) and more | Session token |

Listings and property search keep the paths they have always had, for example `POST /properties/search`. They now accept `Authorization: Bearer` too.

## Browse the OpenAPI document

The whole Fondaro API describes itself in one OpenAPI 3 document at [`https://api.fondaro.com/openapi/fondaro.json`](https://api.fondaro.com/openapi/fondaro.json). It is public. The listings and property search part alone stays at [`/openapi/properties.json`](https://api.fondaro.com/openapi/properties.json) for existing integrations. Every operation names the scope it needs in `x-required-scopes`. Browse it in the [API reference](https://www.fondaro.com/docs/api-reference.md), or point a code generator or AI assistant at it.

## Read a response

A successful response is JSON: `200`, `201` for a create, or `204` with no body for a delete. A single resource is the object itself. A list is wrapped in an object with `data` and `hasMore`:

```json
{
  "data": [{ "id": "c7d2…", "direction": "outbound" }],
  "hasMore": true,
  "nextOffset": 1
}
```

Record ids are UUIDs, except leads (integers) and people (user ids such as `user_2abcDEF`). Times are ISO 8601 in UTC; date-only fields are `YYYY-MM-DD`. [Errors and limits](https://www.fondaro.com/docs/api/errors-and-limits.md) lists the error envelope, the paging styles, idempotency and rate limits.

## Handle new versions

The `/v1` routes only change by adding: new routes, new fields, new optional parameters. Build your client to ignore fields it does not know. A change that breaks a client would arrive as `/v2`, announced in the changelog, with `/v1` still working.

Source: https://www.fondaro.com/docs/api/overview