Connect Pipedrive

Pipemetry reads your Pipedrive deals, their changelog (the record of what each field changed from and to), and the persons attached to each deal. It never creates or changes a deal.

The same walkthrough is built into the app, on the Pipedrive card under Onboarding.

What Pipemetry needs from you

Read access to your deals and to their change history. History is the part people miss: on Pipedrive it lives under a different permission from the deals themselves.

You give it one of two ways:

a personal API token, which inherits the permissions of the user it belongs to; or
OAuth — an App Client ID plus a Refresh token.

Choose the connecting user first — it changes your numbers

Pipedrive applies visibility per deal. A non-admin connection sees a subset of your pipeline with no error anywhere: every screen looks healthy and the forecast is simply built on less than your business.

Prefer an admin user, or a dedicated integration user who can see every deal you want forecast.
Pipemetry checks whether the connected user is an admin and warns on the card when it is not.
It cannot tell you how many deals are hidden from a non-admin token — Pipedrive’s own deal count is itself scoped to what the caller can see — so it reports what it can measure and says the rest is unknown.

Option A — a personal API token (fastest)

Sign in to Pipedrive as the user whose access Pipemetry should inherit (see the section above before choosing).
Open your API token — Pipedrive documents the path under Personal preferences → API in the linked article below.
Paste it into the API token field on the Pipedrive card and Save. Pipemetry stores it encrypted and never shows it again.

Option B — OAuth

Grant these scopes:

deals:read recents:read contacts:read

contacts:read is optional in the sense that the import succeeds without it — and costly in a way that is easy to miss. It is what the single-threaded-deal signal reads (see What we read below). Without it that alert cannot run, and an alert that cannot run looks exactly like a pipeline with no single-threaded deals in it. Grant it unless you have a reason not to.

recents:read is the one that matters and the one that is easy to miss: Pipedrive keeps the deal changelog under it, not under deals. A token with deal access alone reads every deal and no history, so Pipemetry can only carry today’s values backwards — which is not history.

If you will switch on real-time updates, also grant webhooks:full. Pipedrive’s scope list describes webhooks:read as reading only the webhooks an app created and webhooks:full as “Create, read and delete webhooks” — registering the deal-change subscription, and removing it again when you switch real-time updates off or disconnect, needs the latter. The three read scopes above are enough for polling.

Then paste the App Client ID and a Refresh token into the card and Save.

Verify the connection

Click Verify connection. The card then reports:

the Pipedrive account it reached — the company domain (or company id) and its timezone;
an access verdict: when deals or deal history are not readable it says so and names the scope to grant, without using any auth-failure wording, because the fix is a scope and not a new token;
any required deal fields this connection cannot read, by name;
a warning when the connected identity is not an admin, together with how many deals it can currently see. Pipedrive not telling us whether the user is an admin is a third state and produces no warning — a warning derived from silence would be a fabricated defect report.

The badge turns verified when the access probe comes back clean — deals readable, the required fields present, and changelog access confirmed. A credential that authenticates but demonstrably cannot read changelogs stays configured, because a green badge over a connector that is about to import nothing but anchors is worse than no badge. One honest caveat: if the probe itself fails to run, the connection is stamped verified on the authentication alone, so treat the badge as “we found no problem”, not as “history is proven”.

Backfill your history

Click Backfill deal history. Pipemetry reads your deals and their changelogs and writes them into the same canonical event log Salesforce, HubSpot and Zoho write to.

How far back it can rewind is a property of your account’s changelog retention, not a Pipemetry setting, so nothing here promises a window. After the backfill Pipemetry reports the date your recorded history actually begins. Before that date there are no recorded changes to reconstruct from, and the app says so instead of drawing a flat line that would read as data.

Map your fields

The card mounts a field-mapping editor: tell Pipemetry which Pipedrive field holds each value. Your account’s custom fields are offered by name, because their underlying keys are 40-character hashes — a mistyped hash is accepted by Pipedrive’s read and simply returns nothing, which looks exactly like an empty column.

Out of the box Pipemetry reads value (amount), currency, stage_id, expected_close_date, owner_id, pipeline_id, person_id, org_id, status and add_time (created date). Won and closed are derived from the deal’s status — won is won; won and lost are both closed.

A mapping that names a field this account cannot read is rejected on save, listing the offending canonical fields, rather than saved and left importing nothing.

How the sync stays current

By default this connector polls: on a schedule it looks for deals changed since the last run, reads just those deals’ changelogs, appends the events and advances a watermark. The default cadence is hourly. The connectors list in Settings labels its freshness stamp Last polled rather than Live, because a poll is not something we were pushed — and it offers a Sync now button when you do not want to wait for the next tick.

It paces itself against your account’s API budget, which Pipedrive shares across every integration you run, so it leaves room for the rest of your stack.

Real-time updates (optional)

Switch on real-time updates and Pipedrive pushes each deal change the moment it happens. Registering that webhook subscription is the one thing Pipemetry ever writes to your Pipedrive account — no deal, person or organisation is created or changed — and switching real-time updates off removes it again. On an OAuth connection this needs the webhooks:full scope (see Option B); a personal API token follows the connecting user’s own permissions.

Two things the card enforces rather than assumes:

It needs an admin connection. Pipedrive delivers webhooks only for deals the connecting user can see, so push on a non-admin connection would silently under-deliver for ever. Pipemetry refuses and tells you why instead of turning it on anyway. A connection whose admin status Pipedrive did not report is not treated as eligible — not telling us is not permission.
Registered is not the same as delivering. The card reads back the HTTP status Pipedrive records for the last delivery and warns when the subscription is live but nothing is arriving.

What the single-threaded-deal alert needs

Pipemetry counts the participants on each deal — Pipedrive has no deal-to-contact association object, so participants are the equivalent — and keeps only the count. That count is what the single-threaded-deal alert is computed from; a deal with no count is skipped, so a connection that cannot read participants produces an empty alert list, which looks exactly like a pipeline with no single-threaded deals in it. The card therefore reports whether the sweep could look at all.

The read needs Persons: read on the connected identity (an OAuth app needs contacts:read). One Pipedrive-specific wrinkle: Pipedrive meters by token against a budget shared with every integration you run, and the sweep’s whole per-deal loop is one attempt — so a budget exhausted mid-run reports the same “could not look” a missing permission does.

Disconnecting

Disconnect removes the webhook subscription first — after the credentials are gone there is no way left to call Pipedrive, so a subscription still registered at that point could only be removed by you — then deletes the stored credentials, then ends the deals this connector wrote. That last step matters: the event log is append-only, so without it every deal Pipedrive ever imported would keep reconstructing as live pipeline, in the forecast and in alert emails, for a CRM you removed. An as-of-day read of the past is left exactly as it was, and reconnecting restores the deals.