> ## Documentation Index
> Fetch the complete documentation index at: https://help.ciclostrategy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# folk CRM
> Connect folk to track contact, company, and deal-pipeline KPIs in Ciclo — and link live deals to your Actions.
## Overview
[folk](https://folk.app) is a relationship-first CRM for managing contacts, companies, and
deal pipelines. Connecting folk to Ciclo brings that pipeline data into your strategy in two
ways:
Turn folk data — total contacts, new companies, pipeline value, deals won —
into [KPIs](/features/performance-kpis) that refresh automatically and sit
alongside the rest of your strategy.
Link a folk deal to an [Action](/features/actions) so the work to close it
lives on your board — and moves to **Done** automatically when the deal
closes in folk.
Once connected, the sync is one-way (folk → Ciclo): Ciclo reads your folk data to populate
KPIs and update linked Actions. It never writes back to or changes anything in folk.
folk uses a single **workspace-level API key** rather than a per-user login,
so the key grants access to the whole folk workspace. For that reason,
connecting and configuring folk is limited to **organisation administrators**.
## Before you start
* You need an **administrator** role in Ciclo (the **Connect** and **Configure** buttons are
disabled for everyone else).
* You need a folk account with permission to create an **API key** in your folk workspace.
## Connect folk
folk connects with an API key — there's no pop-up login like other integrations. You create
a key inside folk, then paste it into Ciclo once.
Go to **Settings** from the account menu, then open the **Connected Apps**
tab. Find **folk** in the list of available applications and select
**Connect**.
In the dialog that appears, select **Get your API key →**. This opens folk's
API key settings for your workspace. Create a new key and copy it. (In folk
you can also reach this from **Settings → API keys**.)
Back in Ciclo, paste the key into the **API key** field and select
**Connect**. Ciclo validates the key with folk and stores it securely — the
key is encrypted and never shown again.
On success, folk shows a green **Connected** status in the list. You're
ready to add KPIs and link deals.
Treat the API key like a password. If it's ever exposed, revoke it in folk and
reconnect with a fresh key — your KPIs and linked Actions reconnect
automatically.
## Track folk KPIs
KPIs are configured from the **Connected Apps** tab, then appear on your team's
[Performance page](/features/performance-kpis) and refresh on a schedule — no manual updates.
On the **folk** row in Connected Apps, select **Configure**. This lists any
folk KPIs you've already created.
Select **Add New KPI** and give it a clear **KPI Name** (e.g. "New contacts
this month").
Choose a **Query Template** as your starting point — see the [catalogue
below](#available-folk-kpis). Workspace-wide templates (People, Companies)
work immediately. Group and deal templates need you to pick a **Group**.
If the template tracks a specific list or pipeline, select the folk
**Group** it applies to. Ciclo resolves the group automatically — you just
pick it by name.
For deal KPIs, a **Status** dropdown appears, populated with the real stages
from your folk pipeline (e.g. *Qualified*, *Closed-won*). Pick the stage you
want to measure — it updates the query for you.
Select **Create KPI**. It now appears on your [Performance
page](/features/performance-kpis) and refreshes automatically.
### Available folk KPIs
Count contacts across your entire folk workspace. - **Total People** — every
contact in the workspace. - **New People (7 / 30 / 90 days)** — contacts
added in the last week, month, or quarter.
Count companies across the workspace. - **Total Companies** — every company
in the workspace. - **New Companies (30 days)** — companies added in the
last month.
Measure the size and growth of a specific folk group or list of contacts. -
**Group Size (People)** — contacts in the selected group. - **People Added
to Group (7 / 30 days)** — recent additions to the group.
Track a deal pipeline by stage and value. - **Open Deals** / **Deals in
Stage** — count of deals at a chosen stage. - **Deals Won (7 / 30 days)** —
deals closed-won in the period. - **Total Pipeline Value** — summed value of
open deals. - **Won Revenue (30 days)** — summed value of deals won in the
last month.
In folk, a deal's **stage** and **value** are custom fields, and stage names
are specific to your workspace. That's why the stage dropdown reads the real
options straight from your pipeline — so the KPI always matches how your team
actually labels its deals.
## Link folk deals to Actions
You can attach a live folk deal to an Action so the work to win it lives on your
[Actions board](/features/actions), with the deal's value, close date, owner, and contacts
carried across.
Create or open an [Action](/features/actions), then choose the **Connect**
option to link an external item.
Select **folk** as the source, pick the **group** that holds your deals,
then choose the **deal** to connect. Ciclo fills in the action's title, due
date (the deal's close date), and details from the deal.
Save, and the action stays connected to the deal.
**Automatic status sync.** When a connected deal is marked **closed** in folk,
Ciclo moves the linked action to **Done** on your board — so closing the deal
in your CRM keeps your strategy board honest without any extra clicks.
## Customising a KPI (optional)
You don't need any of this to get great results — the built-in templates are designed to be
accurate on their own. Pick a template (and a group/stage where prompted) and you're done.
Expand the sections below only if you want to fine-tune or go further.
If a template is close but not quite right, you can adjust it instead of starting from
scratch. Every KPI has an editable **Query** field — for example, change the window from
the last 30 days to the last 14 days by editing `{date-30d}` to `{date-14d}`, or pick a
different pipeline stage from the dropdown. The templates and dropdowns simply fill this
field in for you; editing it is optional.
Power users can replace the query entirely using folk's own API path and filter syntax —
anything folk's API supports, you can track. For everything that's possible, see:
The full set of folk endpoints and filters you can use in a query.
One thing to watch when hand-editing: folk silently ignores an unrecognised stage value
and returns **all** records instead of erroring, which would quietly inflate a KPI. When
in doubt, use the stage dropdown — it always produces a correct query.
## Disconnecting folk
To disconnect, select **Disconnect** on the folk row in Connected Apps. Ciclo shows which
KPIs and Actions rely on folk before you confirm.
Disconnecting **preserves history** — your KPIs keep their recorded values and
linked Actions keep their data. They simply stop syncing until you reconnect,
at which point they pick up automatically.
## Best practices
* **Track what's strategic** — connect the few pipeline metrics that map to a goal, not every
possible count.
* **Match your stages** — use the stage dropdown so KPIs follow how your team labels deals.
* **Link key deals** — connect significant deals to Actions so the work to close them is
visible and accountable.
* **Keep the key safe** — rotate the API key in folk if it's ever exposed, then reconnect.
## Related