---
title: "Score Contacts by Signal Activity"
method: POST
path: "/v3/contacts/signal-score"
tags: ["Signals"]
---

# Score Contacts by Signal Activity

`POST /v3/contacts/signal-score`

Score contacts by their active buying signals. Returns the aggregate Signal Score - a `[0, 1]` value - plus the active signal breakdown per contact.

Accepts up to 100 contacts. Each contact is resolved to a Lusha person ID and company ID server-side (identity only - no PII is revealed) before scoring. Provide one of:
- `id` (encrypted Lusha contact ID)
- `linkedinUrl`
- `email`
- `firstName` + `lastName` + (`companyName` or `companyDomain`)

Each result is one of:
- A **scored entry** - `signalScore`, `signalTypes`, and `noActiveSignals`.
- A **`NOT_FOUND`** entry - identity resolution failed for the supplied identifier.
- A **`NO_SCORE`** entry - the contact resolved, but the scoring engine returned nothing for it.

> **Note:** A full outage of the identity-resolution provider is never masked as `NOT_FOUND` - it returns a retryable `502` instead, so callers can retry rather than treating the batch as authoritatively unresolved.

> **Billing:** 1 credit is charged per scored row via `signal_score_contact_reveal`. This action is currently limited-availability - while it isn't yet seeded on an account's pricebook, the endpoint stays free (`billing.creditsCharged` is `0`). Error rows (`NOT_FOUND` / `NO_SCORE`) are never charged.

## Request body

- V3SignalScoreContactsRequest
  - `contacts` V3SignalScoreContactItem[], required
    - `clientReferenceId` string
    - `id` string — Encrypted Lusha contact ID (vN.…).
    - `linkedinUrl` string
    - `email` string, email
    - `firstName` string
    - `lastName` string
    - `companyName` string
    - `companyDomain` string

## Response `200`

Successful response

- V3SignalScoreContactsResponse
  - `requestId` string, uuid
  - `results` V3SignalScoreContactResult[]
    - `clientReferenceId` string
    - `id` string — Encrypted Lusha contact ID for scored entries. On NOT_FOUND, echoes the supplied id, if one was given.
    - `fullName` string
    - `company` V3SignalScoreContactCompanyRef — Company the contact was scored at.
      - `id` string
      - `name` string
      - `domain` string
    - `signalScore` number — Aggregate signal score. Absent on error entries.
    - `signalTypes` string[] — Signal types currently active for this contact (canonical camelCase). Absent on error entries.
    - `noActiveSignals` boolean — True when the contact resolved and scored but has no active signals (signalScore is 0). Absent on error entries.
    - `error` V3ItemError — Per-item error in a batch response
      - `code` 'NOT_FOUND' | 'COMPLIANCE_RESTRICTED' | 'ENRICH_FAILED' | 'NO_SCORE'
      - `message` string
  - `billing` V3Billing — Credit usage summary for a V3 API request
    - `creditsCharged` integer — Total credits charged for this request
    - `resultsReturned` integer — Number of successful results returned

## Other responses

- `400` — Bad request - invalid input data
- `401` — Unauthorized - invalid or missing API key
- `402` — Payment required - insufficient credits
- `403` — Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
- `429` — Too many requests - rate limit exceeded
- `502` — Bad gateway - upstream identity resolution provider is unavailable. Retryable.

---

[API](https://skmtc.net/lusha/apis/lusha-api-documentation.md) · [All operations](https://skmtc.net/lusha/apis/lusha-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lusha/lusha-api-documentation/revisions/8e62fb5a9414/schema)