External APIs & Integrations

Every third-party / external service the platform talks to — what it provides, which part of the system calls it (Worker handler · n8n · a BigQuery transfer · the build), and the secret that authenticates it. This is the integration map; for the platform’s own internal routes see worker-endpoints.md, and for the n8n jobs themselves n8n-workflows.md. Verified against the code 2026-05-23.

All Worker secrets are set via wrangler secret put (never committed); the n8n-held credentials live in the n8n tenant. Two callers dominate: the Worker (live, at the edge) and n8n (async / ETL / fallback).

---

Data warehouse & Google data

Service	Used for	Called by	Auth
Google BigQuery (bigquery.googleapis.com)	The warehouse — almost every read, plus DDL/DML	Worker bq/client.js (all BQ handlers), bq-execute, bq-admin, bq-create-table	BQ_SERVICE_ACCOUNT_JSON → JWT via oauth2.googleapis.com
Google Ads API (googleads.googleapis.com)	Live keyword search volumes (county-level)	Worker keyword-planner.js	GOOGLE_ADS_DEVELOPER_TOKEN + OAuth (GOOGLE_ADS_CLIENT_ID/_SECRET/_REFRESH_TOKEN/_CUSTOMER_ID/_LOGIN_CUSTOMER_ID)
Google data via BigQuery Data Transfer — GA4, Search Console, GMB, Google Ads, Merchant Center	Lands in BQ on a schedule; the Worker only reads it	Google-side transfer (not a Worker call) → read by Worker ga4-stats, gsc-stats, gbp-stats, ads-stats, gmc-stats	Google transfer service; see bigquery-and-sync.md

CSO / Pobal / Tailte / CRO / data.gov.ie are data sources loaded into BQ (provenance, not live APIs) — see cso-area-data.html.

AI / ML

Service	Used for	Called by	Auth
OpenAI (api.openai.com)	Embeddings for every Vectorize index + Whisper speech-to-text	Worker: vector-*, deals-vector-*, company-knowledge-*, case-studies-reindex, docs-reindex/docs-search, crawl-website, deal-patterns, stt	OPENAI_API_KEY
Anthropic Claude (api.anthropic.com)	The AI advisor + generated insights + the docs bot	Worker: ai-advisor, discovery-insights, map-advisor, deal-patterns, docs-search	ANTHROPIC_API_KEY

Rank · SEO · local search

Service	Used for	Called by	Auth
SerpAPI (serpapi.com)	SERP rank grids, local rank checks, prospect search/enrich/audit, GBP live, NAP	Worker: serp-grid, serp-local, prospect-search/-enrich/-audit, competitor-enrich, gbp-live, lib/insites-nap · + n8n batch refresh loops	SERPAPI_KEY
Pleper (scrape.pleper.com)	GBP profile scrape (photos, posts, hours, categories)	Worker lib/pleper → prospect-audit, gbp-live, prospect-pleper-refresh, competitor-enrich · + n8n batch	PLEPER_API_KEY + PLEPER_API_SIG
Ahrefs (api.ahrefs.com)	Keyword volumes + SEO metrics; + usage meter (subscription-info/limits-and-usage)	Worker: ahrefs-by-url, ahrefs-seo, prospect-intel, discovery-suggest, saymore-keyword-matrix, api-usage-report-cron (meter)	AHREFS_API_KEY
InSites (api.insites.com / app.insites.com)	Digital-footprint + LRC audits, share links, report settings	Worker: insites-settings, insites-share-link, insites-report-summary, grid-map-build, ai-advisor · + n8n (submit / poll / callback — the primary path)	INSITES_API_KEY_DF, INSITES_API_KEY_LRC, INSITES_PUBLIC_KEY (DF vs LRC are separate keys)

CRM · deals · delivery · support

Service	Used for	Called by	Auth
FCR CRM (Dynamics) (crmprod.fcrmedia.ie)	Account + order data (the billing source of truth)	Worker check-account, check-enrichment · + n8n dashboard-account	internal CRM auth
HubSpot (api.hubapi.com)	Deals, engagements (notes/emails/calls), properties; daily usage via rate-limit headers	Worker: hubspot-deal-context/-live/-deals-search/-engagements-sync/-properties, ai-advisor, api-usage-report-cron (usage headers) · + n8n sync to BQ	HUBSPOT_ACCESS_TOKEN
Teamwork Projects (fcrie.teamwork.com)	Build projects, milestones, tasks	Worker teamwork-project, build-detail, ai-advisor (live single-project) · + n8n bulk sync → BQ	TEAMWORK_PROJECTS_API_KEY
Teamwork Desk (fcrie.teamwork.com/desk)	Support tickets (open + closed history)	Worker teamwork-desk-ticket(s), twd-deep-dive, build-detail, ai-advisor	TEAMWORK_DESK_API_KEY (Bearer) + TEAMWORK_DESK_WEBHOOK_SECRET (HMAC for the deep-dive webhook)

Marketing · listings · comms

Service	Used for	Called by	Auth
Meta (Facebook) Marketing API (graph.facebook.com)	Audience reach estimates per area	Worker meta-reach, meta-reach-batch	META_ACCESS_TOKEN + META_AD_ACCOUNT_ID
Yext	Publisher-listings sync	n8n (Worker yext-sync delegates to n8n; yext-listings reads the BQ cache)	n8n-held Yext creds
iovox	Call-tracking data	Ingested to BQ via n8n/ETL; Worker iovox only reads BQ	n8n/ETL
Roam (Ro.am) (api.ro.am)	Post AM-filed briefs to the Development group; advisor chat surface	Worker ai-advisor (send_brief_to_development)	ROAM_BEARER + ROAM_DEV_GROUP_ID

Orchestration

Service	Used for	Called by	Auth
n8n (fcrmedia.app.n8n.cloud/webhook)	Async jobs, ETL, and Worker fallback — InSites submit/poll, CRM account fetch, HubSpot/Teamwork/Yext/iovox sync, batch SerpAPI+Pleper refresh	Worker → n8n (ai-advisor, discovery-df-compare, hubspot-chat, insites-poll, prospect-engagement, report-annotate) and the web UI → n8n directly (dashboard-account, GA4/GSC/GBP stats, etc.)	N8N_API_KEY

Cloudflare platform (bindings, not HTTP APIs)

Binding	Service	Used for
VECTORIZE / COMPANY_KNOWLEDGE_VECTORIZE / DEAL_VECTORIZE / DOCS_VECTORIZE	Vectorize	Semantic search (site portfolio, company knowledge, deal history, docs bot)
CACHE / REPORTS	Workers KV	Response cache + Discovery report storage
ADVISOR_CSV / SERP_SNAPSHOTS	R2	CSV attachments + SERP HTML/PNG snapshots
BROWSER	Browser Rendering	Headless-Chrome screenshots (serp-screenshot)
BRIEF_QUEUE (+ DLQ)	Queues	Deal-brief refresh fan-out
PROGRESS_DO	Durable Objects	Strongly-consistent advisor progress state for the HubSpot card poller
API_USAGE	Analytics Engine	Per-call counter for worker→Teamwork calls (lib/api-usage.js countedFetch); read back by the weekly usage report (see below)

Client-side / CDN (browser, not the server)

• OpenStreetMap tiles + unpkg (Leaflet) — map rendering in the embedded maps (area-map-embed, grid-map-build).
• Google Maps deep-links (maps.app.goo.gl) — links in case studies / reports (not an API call).

Usage & cost telemetry

A weekly external-API usage report (api-usage-report-cron.js, on the Mon 08:00 UTC cron + on-demand GET /dashboard-api-usage-report?dry=true) DMs our usage of the paid providers to Ro.am, each read from its best source. Two sourcing strategies: a vendor meter (account-level, captures worker and n8n — true totality) where the provider exposes one, else a worker counter (API_USAGE Analytics Engine via countedFetch, worker-originated only):

• Ahrefs (vendor meter) — /v3/subscription-info/limits-and-usage (free, no units). Weekly run-rate + projection vs the unit cap.
• SerpAPI (vendor meter) — serpapi.com/account: this-month usage vs the plan quota. Account-level, so it covers worker enrich/grid/local + n8n.
• HubSpot (headers) — X-HubSpot-RateLimit-Daily(-Remaining) off one cheap call. The dedicated account-info/v3/api-usage/daily endpoint is API-key only (404s for private-app tokens). Daily counter — today’s headroom, not a weekly sum.
• Teamwork (worker counter) — countedFetch on the Teamwork handler choke points. Worker-originated only — excludes the nightly n8n Desk/Projects sync.
• Pleper (worker counter) — counts scrape jobs (the submit call, not the commit/poll round-trips) via countedFetch in lib/pleper.js. Worker-originated only — excludes any n8n Pleper calls.

The worker-counter providers (Teamwork, Pleper) need AE_READ_TOKEN (a Cloudflare API token, scope Account Analytics: Read) + the CF_ACCOUNT_ID var to read the dataset back; the vendor-meter providers work without it.

---

Source of truth: external hosts + env.* secrets in worker/src/**. If you add an integration, add its secret via wrangler secret put, wire CORS if a browser calls it, and add a row here.