GET /v1/decisions/{id}

Call	GET /v1/decisions/{id}
Price	free
Scope	decisions:write
Operation id	getDecision

What it does

Fetch a decision your organization made, exactly as it was returned (decisions are immutable). Use it to audit an answer or to recover a response you lost. Free. Scope: decisions:write.

Example request

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

Request

curl -X GET 'https://api.askverdict.io/v1/decisions/dec_01JC3Z4Y8R9K2M5N7P1Q3S5T7V' \
  -H "Authorization: Bearer $VERDICT_API_KEY"

Example response

200: The stored decision.

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": "qualify_firm",
  "p": 0.82,
  "answer": "fit",
  "reason_code": "icp_type_and_size_match",
  "reason": "Registered investment adviser, $400M AUM band, 12 employees; matches ICP type and size.",
  "evidence": [
    {
      "source": "sec_edgar",
      "url": "https://adviserinfo.sec.gov/firm/summary/298765",
      "observed_at": "2026-10-28",
      "label": "Form ADV Part 1A"
    }
  ],
  "fit": 0.82,
  "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.32
}

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The decision id.
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.

Response fields (200)

Schema Decision.

Field	Type	Required	Description
id	string	no	The decision id. Report outcomes against it.
decision	enum: “qualify_firm”	no	The decision name.
version	enum: “2026-11-01”	no	API version that served the decision.
question_set_version	string (date)	no	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	no	Decision model that answered: always jev (ADR-0008).
p	number	no	Calibrated probability (spec 6.4). Always present.
answer	enum: “fit”, “not_fit”	no	fit or not_fit: p applied to your threshold.
reason_code	enum: “icp_type_and_size_match”, “icp_type_match_size_mismatch”, “icp_size_match_type_mismatch”, “icp_type_and_size_mismatch”, “icp_geography_mismatch”, “icp_exclusion_filter_match”, “firm_inactive”, “insufficient_firm_data”	no	Why, from the fixed qualify_firm reason-code enum.
reason	string	no	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	no	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	no	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	no	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	no	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	no	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	no	When the decision was made. Decisions are immutable.
fit	number	no	Probability the firm fits the ICP; equal to p.
firm	FirmSummary	no	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.
relevant	number	no	Probability the event matters for the ICP’s offer; equal to p.
act_now	number	no	Probability that now is the time to act on it.
window_days	integer or null	no	Days left to act, or null when there is no clear window.
event_id	string	no	The scored event (an inline event is stored and given an id).
people	array of object	no	The whole roster ranked best first, each with p.
people[].index	integer	yes	Zero-based position of the person in your roster.
people[].ref	string or null	yes	Your ref for the person, or null if you gave none.
people[].rank	integer	yes	Rank, 1 is best.
people[].p	number	yes	Calibrated probability that this is the right person to write to.
state	enum: “interested”, “meeting_requested”, “question”, “objection_price”, “objection_timing”, “objection_fit”, “not_decision_maker”, “referral”, “out_of_office”, “unsubscribe”, “bounce”, “wrong_person”, “other”	no	The most likely state of the thread.
next_action	enum: “reply”, “book_meeting”, “answer_question”, “handle_objection”, “forward_to_referral”, “find_other_contact”, “retry_later”, “unsubscribe”, “stop”, “escalate_to_human”, “none”	no	What the agent should do next.
send	number	no	Probability that sending now is right; equal to p.
hold_reason	enum: “upstream_decision_weak”, “upstream_decision_missing”, “inbox_health_degraded”, “daily_volume_limit”, “recently_contacted”, “message_issue”, “recipient_opted_out”, “low_confidence”, null	no	Why to hold, when answer is hold; null when answer is send.

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).
403	The key lacks the scope this operation needs (forbidden_scope).
404	The resource does not exist in this organization (not_found).
429	Rate limited (rate_limited). Wait Retry-After seconds.
500	Unexpected server error (internal). Not billed; 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.