Spreadsheet Add-ins

The Pidgr spreadsheet add-ins bring live campaign metrics into the tools your reporting already lives in. Once configured, a single formula returns an up-to-date value straight from your Pidgr organization:

=PIDGR.METRIC("campaign_id", "metric")   // Excel
=PIDGR("campaign_id", "metric")          // Google Sheets

Values refresh automatically (cached for about 5 minutes), so dashboards, weekly reports, and compliance trackers stay current without manual exports.

Both add-ins authenticate with the same credential: a read-only API key scoped to your organization.

Create a read-only API key

1. Open the Pidgr admin dashboard and go to Organization → API Keys.
2. Create a new key with the campaigns read permission (PERMISSION_CAMPAIGNS_READ) and nothing else.
3. Copy the key — you’ll paste it into the add-in during setup below.

Security model

The key is read-only: it can report on campaigns but can never create, start, or modify anything. It operates only within its own organization, and you can revoke it at any time from the same API Keys page. Rate limits apply per key, so a runaway spreadsheet can’t affect the rest of your integrations.

Tip

Create a dedicated key per team or per workbook owner. If a spreadsheet is shared beyond its intended audience, you can revoke that one key without disturbing anyone else’s reports.

Excel add-in

The Excel add-in provides the PIDGR.METRIC custom function and a task pane for configuration. Add-in assets are served from https://addons.pidgr.com, and the manifest lives at:

https://addons.pidgr.com/manifest.xml

Requirements

• Excel from Microsoft 365 (web or desktop). Custom functions are a Microsoft 365 capability — they are not available in perpetual (one-time purchase) editions of Excel.

Install for your whole organization (recommended)

If you’re a Microsoft 365 administrator, deploy the add-in centrally so everyone gets it without individual setup:

1. Open the Microsoft 365 admin center and go to Settings → Integrated apps.
2. Choose Upload custom apps and select Office Add-in.
3. Provide the manifest — either the URL https://addons.pidgr.com/manifest.xml or the downloaded manifest file.
4. Assign the users or groups who should get the add-in, and confirm the deployment.

The add-in then appears for assigned users in Excel under Insert → Add-ins.

Note

Centralized deployments can take a few hours to propagate to all assigned users.

Install for yourself (sideload)

For a quick trial, or if you can’t use centralized deployment:

• Excel on the web: go to Insert → Add-ins → Upload My Add-in and upload the manifest file.
• Excel for Mac (desktop): copy the manifest file into ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/ (create the wef folder if it doesn’t exist), then restart Excel.

Configure your API key

1. In Excel, open the Pidgr task pane (from the ribbon).
2. Paste your read-only API key and save.

The key is stored in the add-in’s own protected storage (OfficeRuntime.storage) — it never appears in formulas, cells, or the workbook file, so sharing a workbook never shares your key.

Use it

=PIDGR.METRIC("cmp_2f8a91", "ack_rate")

Google Sheets add-on

The Google Sheets add-on provides the PIDGR custom function via a container-bound Apps Script — the script is attached to a specific spreadsheet rather than installed account-wide.

There are two ways to get it into a spreadsheet:

• Start from a Pidgr export or template. Workbooks exported from the Pidgr admin dashboard (see Export from the admin dashboard) come with the formulas pre-wired and an instructions sheet.
• Add it to an existing spreadsheet:
  1. Open the spreadsheet and go to Extensions → Apps Script.
  2. Paste the contents of the add-on’s Code.gs into the script editor and save.
  3. Authorize the script when prompted.
  4. Reload the spreadsheet, then open the Pidgr → Configurar menu and paste your read-only API key in the sidebar. Like the Excel add-in, the key is held in the document’s script storage — never in cells or formulas.

The Code.gs file is currently distributed by Pidgr directly (via the export template or your Pidgr contact); the add-on is not yet listed on the Google Workspace Marketplace.

Use it

=PIDGR("cmp_2f8a91", "ack_rate")

Available metrics

Both add-ins expose the same metrics:

Metric	Description
total_recipients	Number of recipients targeted by the campaign
acked	Number of recipients who have acknowledged
missed	Number of recipients who have not acknowledged
ack_rate	Acknowledgement rate (acked over total_recipients)
status	Current campaign lifecycle status
audience_size	Number of users in the campaign’s resolved audience
started_at	When the campaign started
completed_at	When the campaign completed (empty while still running)

Export from the admin dashboard

You don’t have to build a report cell by cell. On any campaign’s detail page in the admin dashboard, use the Export button and choose Excel or Google Sheets. The download is an .xlsx workbook containing:

• a snapshot of the campaign’s current metrics,
• the live formulas pre-wired to the same cells, and
• an instructions sheet covering add-in setup.

The snapshot values are immediately useful on their own; the live formulas activate as soon as the add-in (Excel) or script (Google Sheets) is configured with an API key. For Google Sheets, import the .xlsx into a spreadsheet and add the script as described above.

Refresh and caching

• Values refresh automatically with a cache TTL of roughly 5 minutes — a formula never returns data older than that.
• Requests are batched per campaign: many cells referencing the same campaign resolve with a single API request, so large dashboards stay well within rate limits.

Troubleshooting

Symptom	Meaning	Fix
#NAME?	Excel or Sheets doesn’t recognize the function — the add-in isn’t installed (or, in Sheets, the script isn’t added to this spreadsheet).	Install the add-in / add the script to the spreadsheet, then reopen the workbook. Org-wide Excel deployments can take a few hours to appear.
#PIDGR: Not configured (or similar #PIDGR: message)	The add-in is installed but can’t complete the request — the message states the reason: no API key saved, the key was revoked, the campaign ID doesn’t exist in your organization, etc.	Follow the message: open the Pidgr task pane (Excel) or the script setup (Sheets) and set a valid key, or correct the campaign ID.
#PIDGR: Rate limited	The key hit its rate limit — the API returned 429 with a Retry-After interval.	Wait; the value fills in on the next refresh. Persistent rate limiting usually means many workbooks share one key — create separate keys per team.

Note

#PIDGR: cells are ordinary text errors, not broken formulas — once the underlying cause is fixed, they resolve on the next automatic refresh with no need to re-enter anything.