# Score Companies by Signal Activity

Score companies by their active buying signals. Returns the aggregate Signal Score - a [0, 1] value reflecting the fraction of the company's active signals - plus the active signal breakdown.

Accepts up to 100 companies, each identified by exactly one of id, domain, name, or email. All identifiers are resolved to Lusha company IDs server-side before scoring.

Each result is one of:
- A scored entry - signalScore, signalTypes, and noActiveSignals.
- A NOT_FOUND entry - the company service could not resolve the supplied identifier.
- A NO_SCORE entry - the company resolved, but the scoring engine returned nothing for it.

> Billing: 1 credit is charged per scored row via signal_score_company_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.

Endpoint: POST /v3/companies/signal-score
Security: ApiKeyAuth

## Request fields (application/json):

  - `companies` (array, required)

  - `companies.clientReferenceId` (string)
    Caller-supplied token echoed back on the matching result.
    Example: "ref-1"

  - `companies.id` (string)
    Encrypted Lusha company ID (vN.…). Legacy numeric IDs accepted during the transition window.
    Example: "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345"

  - `companies.domain` (string)
    Example: "www.microsoft.com"

  - `companies.name` (string)
    Example: "Apple"

  - `companies.email` (string)
    Must be a valid email address; only the domain part is used for resolution. A malformed email is rejected with 400.
    Example: "jane@acme.com"

## Response 200 fields (application/json):

  - `requestId` (string)
    Example: "5d6f13d2-f6b0-4e55-85d5-04e17f932c1a"

  - `results` (array)

  - `results.clientReferenceId` (string)
    Example: "ref-1"

  - `results.id` (string)
    Encrypted Lusha company ID for scored entries. On NOT_FOUND, echoes the supplied domain/name (or the derived domain, for an email request).
    Example: "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345"

  - `results.name` (string)
    Example: "Acme Corp"

  - `results.domain` (string)
    Example: "www.acmecorp.io"

  - `results.signalScore` (number)
    Aggregate signal score - the fraction of the company's active signals. Absent on error entries.
    Example: 0.42

  - `results.signalTypes` (array)
    Signal types currently active for this company (canonical camelCase). Absent on error entries.
    Example: ["hiringSignalIncrease","websiteVisit"]

  - `results.noActiveSignals` (boolean)
    True when the company resolved and scored but has no active signals (signalScore is 0). Absent on error entries.

  - `results.error` (object)
    Per-item error in a batch response

  - `results.error.code` (string)
    Enum: "NOT_FOUND", "COMPLIANCE_RESTRICTED", "ENRICH_FAILED", "NO_SCORE"

  - `results.error.message` (string)
    Example: "Contact not found"

  - `billing` (object)
    Credit usage summary for a V3 API request

  - `billing.creditsCharged` (integer)
    Total credits charged for this request
    Example: 3

  - `billing.resultsReturned` (integer)
    Number of successful results returned
    Example: 1

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]