POST /v1/decisions/qualify_firm

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

What it does

Is this firm in my ICP? Returns fit as p and the resolved firm.

Call it when your agent meets a company and must decide whether to spend effort on it. Give one firm reference (a domain is easiest) and an ICP profile id. Verdict resolves the firm in its index, reads its public facts (type, size band, HQ) and returns fit as p, answer (fit or not_fit), a reason_code, the resolved firm and cited evidence.

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/qualify_firm' \
  -H "Authorization: Bearer $VERDICT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "firm": {
    "domain": "northfieldcapital.com"
  },
  "icp_id": "icp_01JC3Z4Y8R9K2M5N7P1Q3S5T7V"
}'

Example response

200: The qualify_firm 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": "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
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 QualifyFirmRequest. The qualify_firm input.

Field	Type	Required	Description
firm	FirmReference	yes	A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.
firm.firm_id	string	no	A firm id from Verdict’s index.
firm.domain	string	no	The firm’s web domain.
firm.name	string	no	The firm’s legal or trading name.
firm.hint	object	no	Optional country, city or domain to disambiguate the name.
firm.hint.country	string	no	ISO 3166-1 alpha-2 country of the firm’s headquarters.
firm.hint.city	string	no	City of the firm’s headquarters.
firm.hint.domain	string	no	A domain the firm is known to use.
firm.lei	string	no	The firm’s Legal Entity Identifier.
firm.cik	string	no	The firm’s SEC Central Index Key.
firm.crd	string	no	The firm’s CRD number.
firm.companies_house	string	no	The firm’s UK Companies House number.
icp_id	string	yes	The ICP profile to decide against.

Response fields (200)

Schema QualifyFirmResponse.

Field	Type	Required	Description
id	string	yes	The decision id. Report outcomes against it.
decision	enum: “qualify_firm”	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: “fit”, “not_fit”	yes	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”	yes	Why, from the fixed qualify_firm 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.
fit	number	yes	Probability the firm fits the ICP; equal to p.
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.