Skip to main content
Knock2 continuously calculates lead scores for every identified account and contact, combining firmographic ICP fit with real-time behavioral engagement signals from your website. Scores give your sales and marketing teams an objective, always-current signal to prioritize outreach — no manual scoring rules to maintain.

​
Score anatomy

Each score record captures the numeric score, the subject it belongs to, and a plain-language reason so you always know what drove the result.
​
string
required
The unique identifier for this score record.
​
string
The Knock2 Account ID this score belongs to. null when the score is for a contact only.
​
string
The Knock2 Contact ID this score belongs to. null when the score is for an account only.
​
number
required
The lead score value from 0 (poorest fit) to 100 (strongest fit).
​
string
A plain-language explanation of the key factors that produced this score. Includes both firmographic signals (ICP criteria) and behavioral signals (visit patterns, page depth, recency).
​
string
ISO 8601 timestamp of when this score was calculated.

​
Querying scores

Use GET /v1/scores to retrieve the current score for an account or contact. Pass either account_id or contact_id as a query parameter:

​
Retrieving score history

Set include_history=true to receive the full scoring history for the subject in descending chronological order (most recent first). This is useful for trend analysis, understanding score velocity, and debugging scoring changes.
The response returns an array of score records, each with its own id, score, reason, and created_at timestamp — giving you a complete audit trail of how the score has moved over time.

​
Recent score changes

GET /v1/scores/recent returns the most recent score changes across your entire tenant, sorted by recency. This endpoint is the polling equivalent of the score.changed webhook — each entry in the response mirrors the payload Knock2 sends when a score changes.
This is particularly useful for:

Polling integrations

Sync score changes into downstream systems by periodically fetching the latest batch and processing records newer than your last checkpoint.

Backfill pipelines

Replay recent scoring history when bootstrapping a new integration or recovering from a processing gap.

Alerting workflows

Detect when high-value accounts cross a score threshold and trigger notifications or CRM tasks.

Analytics

Track score distributions and velocity trends across your entire identified visitor base.

​
score.changed webhook

Instead of polling GET /v1/scores/recent, you can subscribe to push notifications by registering a score.changed webhook via POST /v1/webhooks. Knock2 calls your endpoint in real time whenever a score is recalculated, delivering the same payload structure as the polling response.
See the Webhooks guide for full details on registering endpoints, verifying signatures, and handling retries.
Scores are recalculated automatically as new visit data arrives. You don’t need to trigger recalculation manually — Knock2 handles this in the background whenever a session event or enrichment update is processed for an account or contact.