POST /v1/decisions/score_signal

Call	POST /v1/decisions/score_signal
Price	$0.005 per call, billed only when an answer is returned
Scope	decisions:write
Operation id	scoreSignal

What it does

Does this event matter for my offer, and is now the time? Returns relevant, act_now and window_days.

Call it when an event (a filing, a raise, an officer change) arrives and you must decide whether it is worth acting on now. Give an event_id from GET /v1/events or an inline event, and an ICP profile id. Returns relevant as p, act_now, window_days, answer (relevant or not_relevant) and a reason_code.

Price: $0.005 per call (x-verdict-price-usd), billed only when an answer is returned: errors (including decision_unavailable, 503 with Retry-After) and refused calls are free. Send X-Max-Cost-USD to cap spend and Idempotency-Key (required) to retry safely; a repeated key within 24 hours returns the stored response and bills nothing. Every response carries the common envelope: id, p (always present, calibrated), answer, reason_code, reason, evidence, calibration, cost and balance_usd. Report what happened next with POST /v1/outcomes.

Scope: decisions:write.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

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"
}'

Example response

200: The score_signal decision, in the common envelope.

200 response

{
  "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
}

Parameters

Name	In	Type	Required	Description
idempotency-key	header	string (uuid)	yes	A UUID you generate per logical request. Required on every POST. Repeating it within 24 hours returns the stored response and bills nothing; reusing it with a different body returns 409 idempotency_conflict.
x-max-cost-usd	header	string	no	Maximum you are willing to pay for this call, in US dollars (up to 6 decimals). If the call would cost more, it is refused with 402 max_cost_exceeded before spending.
x-verdict-version	header	string	no	API version to use, a date. Defaults to the version current when the key was created. The current version is 2026-11-01.

Request body

Schema ScoreSignalRequest. The score_signal input.

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.

Response fields (200)

Schema ScoreSignalResponse.

Field	Type	Required	Description
id	string	yes	The decision id. Report outcomes against it.
decision	enum: “score_signal”	yes	The decision name.
version	enum: “2026-11-01”	yes	API version that served the decision.
question_set_version	string (date)	yes	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	yes	Decision model that answered: always jev (ADR-0008).
p	number	yes	Calibrated probability (spec 6.4). Always present.
answer	enum: “relevant”, “not_relevant”	yes	relevant or not_relevant: p applied to your threshold.
reason_code	enum: “event_relevant_and_timely”, “event_relevant_but_stale”, “event_type_not_relevant”, “event_routine”, “firm_not_in_icp”, “event_low_confidence”, “event_superseded”, “insufficient_event_data”	yes	Why, from the fixed score_signal reason-code enum.
reason	string	yes	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	yes	Cited sources, with URLs and dates.
evidence[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
evidence[].url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
evidence[].observed_at	string (date)	yes	Date the source reported the fact.
evidence[].label	string	no	Short description of what the evidence shows.
evidence[].pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.
calibration	Calibration	yes	How p was calibrated (spec 6.4).
calibration.basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
calibration.n_outcomes	integer	yes	Outcomes behind the calibration map used.
calibration.threshold	number	yes	The threshold answer applied to p.
cost	Cost	yes	What this call was billed, itemized. Misses and errors bill nothing.
cost.decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
cost.vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
cost.total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	yes	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	yes	When the decision was made. Decisions are immutable.
relevant	number	yes	Probability the event matters for the ICP’s offer; equal to p.
act_now	number	yes	Probability that now is the time to act on it.
window_days	integer or null	yes	Days left to act, or null when there is no clear window.
event_id	string	yes	The scored event (an inline event is stored and given an id).
firm	FirmSummary	yes	A firm’s id, names, identifiers and public facts.
firm.id	string	yes	The firm id.
firm.name	string	yes	Canonical firm name.
firm.domain	string or null	yes	Primary web domain, if known.
firm.identifiers	object	yes	Registry identifiers, by kind.
firm.identifiers.lei	string	no	Legal Entity Identifier.
firm.identifiers.cik	string	no	SEC Central Index Key.
firm.identifiers.crd	string	no	CRD number.
firm.identifiers.companies_house	string	no	UK Companies House number.
firm.identifiers.wikidata	string	no	Wikidata item id.
firm.type	enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	yes	Coarse firm type.
firm.size_band	enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	yes	Employee-count size band.
firm.hq	object	yes	Headquarters location.
firm.hq.country	string or null	yes	ISO 3166-1 alpha-2 country.
firm.hq.region	string or null	yes	State, county or region, as the registry gives it.
firm.hq.city	string or null	yes	City.
firm.status	enum: “active”, “inactive”, “dissolved”, “unknown”, “merged”	yes	Registry status.

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
400	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (invalid_request).
401	Missing, malformed, revoked or expired API key, or a bad webhook signature (unauthorized).
402	Payment required: the balance cannot cover the call (insufficient_balance), or the call would exceed X-Max-Cost-USD (max_cost_exceeded). Nothing was spent.
403	The key lacks the scope this operation needs (forbidden_scope).
404	The resource does not exist in this organization (not_found).
409	The Idempotency-Key was reused with a different request, or the first request is still running (idempotency_conflict).
429	Rate limited (rate_limited). Wait Retry-After seconds.
500	Unexpected server error (internal). Not billed; retry with the same Idempotency-Key.
503	Temporarily unavailable: the decision model failed, timed out or is rate limited, or decisions are switched off (decision_unavailable), or a vendor the call depends on is unavailable (vendor_unavailable, phase 2). Not billed. Wait Retry-After seconds and retry with the same Idempotency-Key.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.