# n8n

> Connect Fondaro to n8n with the n8n-nodes-fondaro community node: API keys, real-time triggers, polling and actions.

[n8n](https://n8n.io) is a workflow tool you run in the cloud or on your own server. The `n8n-nodes-fondaro` community node starts workflows when something happens in your CRM and creates, finds and updates CRM records. It ships three nodes:

| Node | Use it to |
|---|---|
| **Fondaro** | Create, find, list and update leads, deals, tasks, notes, tags, users and viewings |
| **Fondaro Trigger** | Start a workflow the moment something happens in your CRM (webhooks) |
| **Fondaro Polling Trigger** | Check for new leads on a schedule, when Fondaro can't reach your n8n |

## Install the node

The node is published on npm as `n8n-nodes-fondaro` and is a verified community node, so it works on n8n Cloud and self-hosted. On n8n Cloud, search for "Fondaro" in the node panel. On a self-hosted n8n:

- **From n8n:** open **Settings › Community Nodes**, select **Install** and enter `n8n-nodes-fondaro`.
- **From the command line:** run this in your n8n user folder, then restart n8n.

```bash
npm install n8n-nodes-fondaro
```

## Create an API key

1. In Fondaro, open **Settings › Integrations › n8n** (admins only).
2. Select **Generate key** and give it a name, for example "n8n production".
3. Optionally narrow its **Scopes** or set an **Expiry**, then select **Generate**.
4. Copy the key. It is shown only once; if you lose it, revoke it and generate a new one.

A key acts for the whole agency with admin access, limited by its scopes. Each key allows 120 requests a minute. To rotate, generate a new key, swap it into n8n, check your workflows, then **Revoke** the old one from its **⋯** menu.

| Scope | Allows |
|---|---|
| `leads:read` | Read leads, their activity and calls |
| `leads:write` | Create and update leads, add assignees |
| `deals:read`, `deals:write` | Read, create and update deals |
| `tasks:write` | Create tasks |
| `notes:write` | Create notes |
| `tags:read`, `tags:write` | Read tags, add tags |
| `triggers:subscribe` | Register webhook triggers |
| `users:read` | Look up team members |
| `viewings:read` | Read viewings on your own listings. Not granted by default: tick it when you create the key. |

## Add the credential in n8n

1. In n8n, create a **Fondaro API** credential.
2. Paste the key and leave the base URL as `https://api.fondaro.com`.
3. Save. n8n tests the key straight away.

## Start a workflow on a CRM event

Add a **Fondaro Trigger** node and pick the events. Activating the workflow registers the webhook with Fondaro; deactivating removes it.

| Event | Fires when |
|---|---|
| `lead.created` | A lead lands in your CRM. A CSV import sends one event with every imported lead id. |
| `lead.statusChanged` | A lead's status changes |
| `lead.assigned` | A lead's assignees change |
| `lead.tagged`, `lead.untagged` | A tag is added or removed (one event per tag) |
| `deal.created`, `deal.stageChanged`, `deal.won`, `deal.lost` | A deal is created, moves stage, or closes |
| `task.created`, `task.completed` | A task is created or completed |
| `note.created` | A note is added to a lead |
| `call.logged`, `call.analyzed` | A call is logged, or its review is ready |

Webhooks carry ids only, never contact details: fetch the record with the **Fondaro** node as the next step (for example **Lead › Get**). For a tag event, read the tag with **Tag › Get**. Deliveries are signed, and the trigger node rejects anything unsigned or older than five minutes.

If your endpoint keeps failing, Fondaro retries for several hours, then pauses the subscription after 20 failures in a row. Activate the workflow again to resume.

> **Tip:** Webhooks arrive at least once, not exactly once. For anything that must be complete, also run a daily **Lead › Get Many** with your filters to catch what a paused workflow missed.

## Poll for new leads

If your n8n sits behind a firewall, webhooks can't reach it. Use the **Fondaro Polling Trigger** instead: it checks for new leads on your schedule and keeps its own place, so none are missed.

## Actions

| Resource | Operations |
|---|---|
| Lead | Create, Find, Search, Semantic Search, Match to Listing, Get, Get Many, Get Activities, Get Calls, Update Contact, Update Status, Add Assignees |
| Deal | Create, Get, Get Many, Change Stage, Close Won, Close Lost |
| Task | Create |
| Note | Create |
| Tag | Add, Get |
| User | Get, List |
| Viewing | Get, Get Many |

Rules worth knowing:

- **Find** matches email, phone or external id exactly, among the leads in your CRM. A 404 means no lead matched, not a broken key.
- **Create** needs a language as a BCP-47 tag (`en-GB`, `es-ES`, `sv-SE`). A missing or unknown one is refused. If you set no assignees, your [routing rules](https://www.fondaro.com/docs/dashboard/crm/unassigned.md) assign the lead.
- **Deal › Create** uses your billing currency; set up [Billing](https://www.fondaro.com/docs/dashboard/billing.md) first.
- **Tags** take names or ids. A name that does not exist is created; an id that does not exist is refused and nothing is created. Use ids for anything that must survive a rename or merge. Merging tags in Fondaro sends no per-lead events.
- **Add Assignees** keeps everyone already assigned and adds the people you send. Send `teamIds` to add everyone in a team, up to 50 people per lead.
- **Semantic Search** finds leads whose notes, call transcripts and emails match a description; **Match to Listing** finds leads whose history fits one listing. Both return up to 30 ranked matches with the evidence, and share a limit of 30 requests a minute.
- **Get Calls** and **Get Activities** page with `nextOffset` until `hasMore` is false. A call's `ownerId` is the person who made or took the call, which is not the same as the lead's current assignee; join it to **User › Get**.
- **Viewing › Get Many** reads viewings on your own listings, filtered by listing, lead, agent, status or time. It does not create or change viewings.

## List leads with filters

**Lead › Get Many** calls `GET /integrations/v1/leads` (scope `leads:read`), newest first:

| Parameter | Meaning |
|---|---|
| `tags` | Comma-separated tag names or ids; a lead matches any of them. An unknown entry returns 404. |
| `crmStatus` | `lead`, `potential`, `bad_timing`, `client` or `unqualified` |
| `assigneeId` | Leads assigned to this member |
| `unassigned` | `true` for leads with no assignees (not together with `assigneeId`) |
| `limit`, `offset` | Page size 1 to 100 (default 50), and entries to skip |

```bash
curl -H "Authorization: Bearer fdr_n8n_..." \
  "https://api.fondaro.com/integrations/v1/leads?tags=vip&crmStatus=potential&limit=100"
```

The response is `{ leads, total, hasMore }`. Every lead carries `tags[]` and `origin`: for a lead Fondaro brought you, the ad, the homes and the form answers; otherwise `null`.

## Troubleshooting

| Problem | Fix |
|---|---|
| The credential test fails | The key was mistyped, revoked or expired. Generate a new one. |
| `403` on an action | The key lacks that scope. Generate one with the scopes you need. |
| `429` | A workflow is sending too fast. Add a Wait node; `Retry-After` says when to resume. |
| The trigger stopped firing | The subscription was paused after repeated failures. Activate the workflow again. |

Prefer plain HTTP? Every action is a normal REST call; see the [Integrations API](https://www.fondaro.com/docs/api/integrations.md). Questions: [support@fondaro.com](mailto:support@fondaro.com).

Source: https://www.fondaro.com/docs/dashboard/n8n