score_signal

Does this event matter for my offer, and is now the time? POST /v1/decisions/score_signal. $0.005 per answer. Scope decisions:write.

When to call

Call it when your agent sees something happen to a company (a filing, a raise, a new officer) and must decide whether to act on it. Use an event_id from GET /v1/events or a watch delivery. If the event is not in Verdict’s index, send it inline.

To score many events at once, call GET /v1/events with icp_id: each returned event is scored and billed as one score_signal. To have events pushed to you, create a watch.

Inputs

Either an indexed event or an inline event, plus the ICP.

Field	Type	Required	Description
event_id	string	no	An event from the index.
icp_id	string	no	The ICP profile to decide against.
event	InlineEvent	no	An event the caller supplies, for events Verdict’s index does not hold.
event.type	enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	yes	Event type.
event.firm	FirmReference	yes	A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.
event.firm.firm_id	string	no	A firm id from Verdict’s index.
event.firm.domain	string	no	The firm’s web domain.
event.firm.name	string	no	The firm’s legal or trading name.
event.firm.hint	object	no	Optional country, city or domain to disambiguate the name.
event.firm.lei	string	no	The firm’s Legal Entity Identifier.
event.firm.cik	string	no	The firm’s SEC Central Index Key.
event.firm.crd	string	no	The firm’s CRD number.
event.firm.companies_house	string	no	The firm’s UK Companies House number.
event.occurred_at	string (date-time)	yes	When the event happened.
event.title	string	no	One-line summary of the event.
event.description	string	no	What happened, in plain text. At most 8192 bytes of UTF-8.
event.source_url	string (uri)	no	Where the event was reported.

Outputs

The common envelope plus:

• relevant: probability the event matters for your offer. Same value as p.
• act_now: probability that now is the time to act.
• window_days: how many days the window stays open.
• answer: relevant or not_relevant.
• event_id and firm.

Reason codes

reason_code	Meaning
event_relevant_and_timely	The event type matters for the ICP’s offer and is recent enough to act on now.
event_relevant_but_stale	The event type matters for the ICP’s offer but the window to act has passed.
event_type_not_relevant	The event type does not bear on the ICP’s offer.
event_routine	The event is routine (a periodic or amended filing, a minor change) and carries little signal.
firm_not_in_icp	The firm the event belongs to does not fit the ICP, so the event does not matter.
event_low_confidence	The event’s source confidence or firm keying is low.
event_superseded	The event duplicates or is superseded by a later event for the same firm.
insufficient_event_data	The event carries too few attributes to judge relevance with confidence.

Cost

$0.005 when an answer is returned. Errors bill nothing.

Example

Request

curl -X POST 'https://api.askverdict.io/v1/decisions/score_signal' \
  -H "Authorization: Bearer $VERDICT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "event_id": "evt_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "icp_id": "icp_01JC3Z4Y8R9K2M5N7P1Q3S5T7V"
}'

Response 200

{
  "id": "dec_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "version": "2026-11-01",
  "question_set_version": "2026-11-01",
  "model": "jev",
  "calibration": {
    "basis": "org",
    "n_outcomes": 412,
    "threshold": 0.6
  },
  "latency_ms": 180,
  "created_at": "2026-11-07T14:03:00Z",
  "decision": "score_signal",
  "p": 0.78,
  "answer": "relevant",
  "reason_code": "event_relevant_and_timely",
  "reason": "Form D offering filed 4 days ago; new capital is a buying trigger for this ICP.",
  "evidence": [
    {
      "source": "sec_edgar",
      "url": "https://www.sec.gov/Archives/edgar/data/1601234/000160123426000004/xslFormDX01/primary_doc.xml",
      "observed_at": "2026-11-04",
      "label": "Form D"
    }
  ],
  "relevant": 0.78,
  "act_now": 0.64,
  "window_days": 21,
  "event_id": "evt_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "firm": {
    "id": "frm_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
    "name": "Northfield Capital Advisors LLC",
    "domain": "northfieldcapital.com",
    "identifiers": {
      "crd": "298765",
      "lei": "549300ABCDEF12345678"
    },
    "type": "investment_adviser",
    "size_band": "small",
    "hq": {
      "country": "US",
      "region": "MA",
      "city": "Boston"
    },
    "status": "active"
  },
  "cost": {
    "decision_usd": 0.005,
    "vendor_usd": 0,
    "total_usd": 0.005
  },
  "balance_usd": 18.315
}