n8n

Overview

n8n is a workflow automation platform you can self-host or use in the cloud. The n8n-nodes-fondaro community node connects it to your Fondaro CRM with full coverage: real-time triggers for leads, deals, tasks and notes, plus actions to create, find, and update CRM records.

The package ships three nodes:

• Fondaro (action) creates, finds, lists, and updates leads, deals, tasks, notes, and tags.
• Fondaro Trigger (webhook) starts workflows the moment something happens in your CRM.
• Fondaro Polling Trigger polls for new leads. Use it when your self-hosted n8n sits behind a firewall and cannot receive webhooks.

Installing the node

n8n-nodes-fondaro is a verified community node, so it installs the same way on n8n Cloud and self-hosted instances: no firewall changes, no environment flags, no admin opt-in.

n8n Cloud: open any workflow, click + to add a node, and search for Fondaro. The three Fondaro nodes appear in the panel like built-in nodes; selecting one installs the package automatically. (Verified nodes are allowed on Cloud; you no longer need the HTTP-only workaround below.)

Self-hosted (GUI): open Settings → Community Nodes → Install and enter n8n-nodes-fondaro, or just search for Fondaro in the node panel as on Cloud.

Self-hosted (CLI): run npm install n8n-nodes-fondaro in your n8n user folder, then restart n8n.

Environment bootstrap: set N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true and N8N_COMMUNITY_PACKAGES='[{"name":"n8n-nodes-fondaro","version":"1.0.1"}]'.

Creating an API key

1. In the Fondaro dashboard, open Organization → Integrations → n8n (admin only).
2. Click Generate key, give it a name (for example "n8n production"), and optionally narrow its scopes or set an expiry.
3. Copy the key. It is shown exactly once. If you lose it, revoke it and generate a new one.
4. In n8n, create a Fondaro API credential, paste the key, and leave the base URL as https://api.fondaro.com. Saving the credential runs a live test against your key.

A key is organization-wide and acts with organization-admin access: it can read and write every lead in your organization, not just one member's. Scopes, revocation, and optional expiry are your controls. Each key is rate-limited to 120 requests per minute, which normal automation traffic never approaches.

Rotating a key

There is no separate rotate button, and you do not need one: generate a new key, swap it into your n8n credential, confirm your workflows run, then revoke the old key. Nothing goes down in between.

Prefer not to install a node?

The community node is the recommended path on both Cloud and self-hosted, but you don't have to install anything if your team prefers not to. The Fondaro nodes are a thin wrapper over a normal REST API, so n8n's built-in HTTP Request node (plus the built-in Webhook node for triggers) can do everything the community node does. You set up the API key as a reusable Header Auth credential (Authorization: Bearer fdr_n8n_…, base URL https://api.fondaro.com) and call the /integrations/v1/* endpoints directly. Ask support@fondaro.com for the full HTTP-only walkthrough (Header Auth setup, every endpoint, field rules, webhook signature verification, and a worked example). The rest of this page covers the community node.

Triggers

Real-time webhook trigger

Add the Fondaro Trigger node and pick the events you care about. When you activate the workflow, n8n registers a webhook subscription with Fondaro; deactivating removes it.

Webhook payloads carry ids only, never contact details: fetch the full record back through the Fondaro action node (for example "Lead → Get") as the next step in your workflow. Deliveries are signed (HMAC-SHA256 with a per-subscription secret over a timestamped body) and the trigger node verifies the signature and rejects anything older than five minutes, so spoofed or replayed calls never enter your workflow.

A CSV import fires one lead.created event carrying the full list of imported lead ids, not one event per row.

If your endpoint keeps failing, Fondaro retries on a backoff schedule for several hours, then pauses the subscription after 20 consecutive failures. Re-activating the workflow in n8n registers it again and resumes delivery.

Polling trigger (firewalled self-hosted)

If Fondaro cannot reach your n8n instance (a self-hosted instance behind a firewall or on a private network), webhook deliveries can never arrive. Use the Fondaro Polling Trigger instead: it checks for new purchased leads on the schedule you configure and keeps its own cursor, so no events are lost between polls.

Action reference

All operations live on the single Fondaro node, organised by resource:

Find returns purchased leads only. A lead that has not been purchased into your CRM is not part of your working set, so "Find Lead" answers 404 for it. A 404 means "no purchased lead matched", not that your key is broken.

Create Lead needs a language. Every lead must carry a valid BCP-47 language tag (for example en-GB, es-ES, sv-SE). Casing and _ separators are corrected for you, but a missing or unrecognised value is rejected with a clear error rather than saved. A clean language keeps auto-assignment, language matching, and market reporting reliable. Map your source's language field to a BCP-47 tag in your workflow before the Create step.

Synced leads can auto-assign. If you don't set assignees on Create (and don't flag the lead unassigned), Fondaro runs your auto-assignment rules and routes the lead to a team member. Because Create can add tags, tag-based rules (for example "VIP → senior agent") apply here. When a rule actually assigns a possible duplicate, Fondaro emails your organization's notification address so an admin can review it even though it skips Unassigned. Setting assignees explicitly, or flagging the lead unassigned, always wins over the rules.

Deal Create needs a billing currency. If your organization has no billing currency configured yet, deal creation returns a clear error; set it up under Billing first.

Tags: names, IDs, renames and merges

The tags field (on Tag → Add and Lead → Create) accepts both display names and tag IDs, and treats them differently:

• A plain name is matched case-insensitively; if no tag with that name exists, one is created. This is the classic behavior and every existing flow keeps it.
• A UUID-shaped entry is treated as a tag ID: it must resolve to an existing tag in your organization (by ID first, then by exact name as a fallback), otherwise the call answers 404 and creates nothing. An ID is never turned into a tag name.

Prefer IDs in anything you want to survive a rename or merge. Tags have stable IDs, so renaming or merging in the dashboard never breaks an ID-based flow. A flow that sends the old name after a rename or merge will silently re-create that name as a fresh, empty tag. From node version 1.4.0 the tag dropdowns bind IDs automatically; flows saved earlier keep working by name until you re-pick their tags.

Resolving trigger payloads. lead.tagged / lead.untagged deliveries carry a tagId only. Resolve it with GET /integrations/v1/tags/{tagId} (scope tags:read), which returns { id, name, color, archivedAt }. This works for archived tags and is the only way to name the tag on an untagged event, since it is no longer in the lead's tag set.

Merges don't fan out webhooks. Merging tags in the dashboard re-points the affected leads without firing lead.tagged for each one; a merge is a catalogue correction, not thousands of lead events. Don't build flows that expect per-lead events from a merge.

Archived tags disappear from the tag dropdown but are still accepted when written by ID or exact name, so a mid-flight automation never breaks because an admin tidied the catalogue.

Listing leads and the tag filter

Every lead payload on the integrations API carries a tags[] array: Create, Find, Get, Search, the list endpoint below, and the polling trigger all return each lead's tags as { id, name, color, archivedAt } objects. The field is always present, an empty array when the lead is untagged, so a workflow can branch on tags without a second call. GET /integrations/v1/leads/{leadId}/tags returns the same shape.

The Lead → Get Many operation (node version 1.5.0 and later) lists your CRM working set, newest first by purchase date, and filters it by tags and CRM status. "Which leads carry tag X today" is one request. It calls:

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

The response is { leads, total, hasMore }; total and hasMore describe the filtered set. The endpoint rides the leads:read scope, so every existing key can use it without re-generating. With no parameters it pages through your entire working set.

Tag-driven automations

Reps tag a lead in the dashboard and the automation takes over. Build that in two layers:

Real time (preferred): the lead.tagged trigger. Add a Fondaro Trigger on Lead Tagged; the delivery carries the leadId and the tagId, and the trigger's Only for Tags field can narrow it to the tags you care about. Resolve the tag with GET /integrations/v1/tags/{tagId} (scope tags:read), which returns { id, name, color, archivedAt }, then branch and act. lead.untagged mirrors it for removals. This reacts within seconds and barely touches your rate limit.

Daily reconcile: the list endpoint. Webhook delivery is at-least-once, and a subscription pauses after 20 consecutive failed deliveries, so a robust automation also re-derives its ground truth on a schedule: one Lead → Get Many call with tags=... per day answers "who currently carries the tag" and catches anything the event stream missed, such as a lead tagged while the workflow was deactivated. A daily page or two sits far below the 120 requests per minute each key gets. What that limit does flag is the per-lead sweep (fetching every lead's tags one by one), which the list endpoint replaces.

Troubleshooting

• Credential test fails: the key was mistyped, revoked, or expired. Generate a fresh key and update the credential.
• 403 on an action: your key is missing the scope for that operation. Check the key's scopes on the integration page, or generate a key with the scopes you need.
• 429 responses: a workflow loop is hammering the API past the per-key ceiling. Add batching or a Wait node; the Retry-After header says when to resume.
• Webhook trigger stopped firing: check the integration page; the subscription may have been paused after repeated delivery failures. Re-activate the workflow in n8n to revive it.

Questions? Write to support@fondaro.com.