> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knock2.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead Scores: ICP Fit and Engagement Scoring in Knock2

> Knock2 scores every account and contact on ICP fit and engagement. Learn what score fields contain and how to query current scores and recent changes.

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.

```json theme={null}
{
  "id": "score_01HX...",
  "account_id": "acc_01HX...",
  "contact_id": null,
  "score": 82,
  "reason": "Matches ICP: Series B, 50-200 employees, SaaS vertical. 3 visits to /pricing in the last 7 days.",
  "created_at": "2024-06-01T14:30:00Z"
}
```

<ResponseField name="id" type="string" required>
  The unique identifier for this score record.
</ResponseField>

<ResponseField name="account_id" type="string">
  The Knock2 Account ID this score belongs to. `null` when the score is for a contact only.
</ResponseField>

<ResponseField name="contact_id" type="string">
  The Knock2 Contact ID this score belongs to. `null` when the score is for an account only.
</ResponseField>

<ResponseField name="score" type="number" required>
  The lead score value from **0** (poorest fit) to **100** (strongest fit).
</ResponseField>

<ResponseField name="reason" type="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).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when this score was calculated.
</ResponseField>

## 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:

```bash theme={null}
# Score for an account
curl "https://api.knock2.ai/v1/scores?account_id=acc_01HX..." \
  -H "Authorization: Bearer YOUR_API_KEY"

# Score for a contact
curl "https://api.knock2.ai/v1/scores?contact_id=con_01HX..." \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 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.

```bash theme={null}
curl "https://api.knock2.ai/v1/scores?account_id=acc_01HX...&include_history=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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.

```bash theme={null}
curl "https://api.knock2.ai/v1/scores/recent" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This is particularly useful for:

<CardGroup cols={2}>
  <Card title="Polling integrations" icon="arrows-rotate">
    Sync score changes into downstream systems by periodically fetching the latest batch and processing records newer than your last checkpoint.
  </Card>

  <Card title="Backfill pipelines" icon="database">
    Replay recent scoring history when bootstrapping a new integration or recovering from a processing gap.
  </Card>

  <Card title="Alerting workflows" icon="bell">
    Detect when high-value accounts cross a score threshold and trigger notifications or CRM tasks.
  </Card>

  <Card title="Analytics" icon="chart-line">
    Track score distributions and velocity trends across your entire identified visitor base.
  </Card>
</CardGroup>

## 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.

```json theme={null}
{
  "event": "score.changed",
  "data": {
    "id": "score_01HX...",
    "account_id": "acc_01HX...",
    "contact_id": null,
    "score": 82,
    "reason": "Matches ICP: Series B, 50-200 employees, SaaS vertical. 3 visits to /pricing in the last 7 days.",
    "created_at": "2024-06-01T14:30:00Z"
  }
}
```

See the [Webhooks guide](/guides/webhooks) for full details on registering endpoints, verifying signatures, and handling retries.

<Note>
  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.
</Note>