---
title: "VisitorCompanyFinder docs: pixel, consent, alerts, API"
canonical: https://visitorcompanyfinder.com/docs
last_modified: 2026-10-25
publisher: Surge Software Solutions Private Limited
---

# VisitorCompanyFinder docs: pixel, consent, alerts, API

> Install the pixel, choose a consent mode, set up hot pages, ICP and alert rules, connect CRMs and webhooks, and use the REST API.

Status: company names currently come from demo IP data; licensed IP-to-company data is coming soon. One-click CRM connect, WhatsApp alerts and INR/USD payments are coming soon. Everything else on this page works today.

## Install the pixel

Paste before `</head>` on every page (or add it as a Custom HTML tag in Google Tag Manager). The snippet with your key is under **Settings → Sites**. The pixel is VisitorCompanyFinder by Surge Software ([surgesoftware.co.in](https://surgesoftware.co.in)).

```

<script async src="https://visitorcompanyfinder.com/p.js"

data-site="pk_xxx" data-mode="balanced" data-forms="1">

```

| Attribute | Values | Meaning |

| --- | --- | --- |

| `data-site` | site key | Required. |

| `data-mode` | `balanced` (default) · `strict` | Strict = nothing stored on the device until you call `surgeIntent('consent','granted')`. Use for EU/UK and India (DPDP). |

| `data-forms` | `1` | Listen to form submits. People are stored only if an opt-in checkbox is ticked. |

Size ~4 KB, no third-party calls, `sendBeacon` transport, SPA route changes tracked automatically. The browser never learns which company we matched.

## Privacy model

| Data | What we do | Lawful basis |

| --- | --- | --- |

| Visitor IP | Looked up in memory against company IP ranges, then discarded. Only a daily-rotating salted hash is kept. | Legitimate interest (GDPR 6(1)(f)); in strict mode, after consent. |

| Company match | Only for networks registered to an organisation. Consumer ISP, mobile, hosting and VPN ranges are never attributed. | Company data is not personal data. |

| Pages, time, referrer | Linked to a random first-party id (balanced) or nothing on the device (strict, pre-consent). | Legitimate interest / consent. |

| A person (email, name, title) | Only from a form, chat or `identify` call where the visitor ticked an opt-in. Consent text and time are stored with the record. | Consent (GDPR 6(1)(a), DPDP s.6). |

| Global Privacy Control | Person-level capture is switched off for GPC browsers. | — |

We do **not** resolve anonymous visitors to people through identity graphs, hashed-email cookies or device fingerprinting. Data-subject requests (access, erase, withdraw) are one click in **Settings → Privacy** or one API call.

**India (DPDP Act 2023 + Rules 2025):** there is no general legitimate-interest ground, so for Indian audiences use `data-mode="strict"` with your consent banner, and keep a privacy notice that names Surge as your processor. A notice template is in Settings → Privacy.

## Consent API

```

// From your cookie banner / CMP callback

surgeIntent('consent', 'granted'); // or 'denied' — clears our cookie

// Queue calls before the script loads:

window.surgeIntent = window.surgeIntent || function(){ (surgeIntent.q = surgeIntent.q || []).push(arguments) };

```

## Forms & chat opt-in

Add an unticked checkbox with `data-surge-consent`. Its label text is saved as the consent wording.

```

Yes, Acme may contact me about this request.

```

For chat widgets or custom forms:

```

surgeIntent('identify', { email, name, title,

consentText: 'Yes, Acme may contact me about this chat.' });

```

## Intent scoring

| Signal | Points |

| --- | --- |

| Page view | 2 |

| Hot page (your rules, e.g. /pricing) | its weight; repeat views add less |

| Engaged minute | 1 (max 5 per visit) |

| Return visit | 6 |

| Arrived from an AI assistant | 10 |

| Opted-in form / chat | 25 |

| ICP fit | × 1.25 |

Every signal halves every 14 days. Score = 100 × (1 − e−raw/60). Hot ≥ 60, warm ≥ 30.

## AI summaries

Hot accounts get a summary, a suggested opener and a next step. Requests go to Surge's own Qwen model first; Claude is used only if it fails or times out. Guards reject openers that mention visits or tracking and any output with contact details. Only company-level facts are sent to the model.

## Alerts & integrations

Slack (incoming webhook), Microsoft Teams (Workflows webhook, Adaptive Card), email, HubSpot, Salesforce, Zoho CRM (any data centre incl. `zohoapis.in`) and Pipedrive with a pasted API token (one-click OAuth connect is coming soon), WhatsApp (coming soon: Cloud API with an approved template), webhooks and ReplyDak. Alert rules combine minimum score, ICP-only, page pattern and AI-search arrival, with a cooldown per account.

**WhatsApp templates (coming soon).** WhatsApp only allows business-initiated messages from templates your WhatsApp Business Account has approved. Create a *utility* template named `surge_hot_account` with 4 body variables — company, stage + score, hot pages, dashboard link — and `surge_daily_digest` with 4 — workspace, companies count, top 3 accounts, link.

**Digest.** Settings → Digest: daily (08:00 IST) or weekly (Monday) summary of companies, hot and new accounts, match rate, AI-search arrivals and top pages, sent to the email/Slack/Teams destinations you pick (WhatsApp coming soon). The preview there is the exact email. Schedule `POST /api/cron/digest` hourly with `Authorization: Bearer $CRON_SECRET`.

**IPv6.** Visitors on IPv6 are matched against IPv6 company ranges the same way as IPv4 (narrowest range wins; consumer ISP, hosting and VPN ranges are never attributed). `npm run import:ip2asn -- ip2asn-v6.tsv` loads the free IPv6 ASN table.

## Webhooks

Each POST carries `X-Surge-Event` and `X-Surge-Signature: t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(secret, `t + "." + body`). Reject if older than 5 minutes.

```

{ "event": "account.hot", "company": { "name": "...", "domain": "..." },

"account": { "score": 78, "stage": "hot", "hotPages": ["Pricing"], "aiSources": ["ChatGPT"],

"summary": "...", "opener": "..." },

"contacts": [ /* opted-in people only, with consentBasis + consentAt */ ] }

```

## Cold-email tool pairing

Add the cold-email tool integration (ReplyDak is built in; any tool that accepts a signed webhook works) and an alert rule. Hot accounts are sent as `prospect_account` with the domain, intent and suggested opener; ReplyDak finds role-based decision-makers itself. ReplyDak reports back to `/api/integrations/replydak/inbound?ws=…` (`sequence.started`, `reply.received`, `meeting.booked`) so the account shows its sequence status and alerts don't double-fire.

## REST API (Scale plan)

```

curl -H "Authorization: Bearer svi_live_..." https://visitorcompanyfinder.com/api/v1/accounts?stage=hot

curl -H "Authorization: Bearer svi_live_..." https://visitorcompanyfinder.com/api/v1/accounts/acme.com

curl -X POST -H "Authorization: Bearer svi_live_..." -d '{"email":"a@b.com","kind":"erase"}' .../api/v1/dsr

```