Concepts

Nine nouns cover the whole API. Each has an id with a fixed prefix, so an agent can tell them apart on sight.

Concept	Id prefix	What it is	Created with
Organization	org_	The billing and data boundary. Nothing is ever read across orgs.	POST /v1/signup/verify
Project	prj_	A namespace inside an org, for example outbound or recruiting. Keys, ICPs and watches belong to one.	first one at sign-up
API key	key_	vd_live_... or vd_test_.... Scoped, shown once, revocable, rotatable.	POST /v1/keys
ICP profile	icp_	Who you sell to and what you sell, as text plus optional filters. Every decision is made against one.	POST /v1/icps
Firm	frm_	A company in Verdict’s index, with its identifiers (domain, LEI, CIK, CRD, Companies House number).	resolved for you
Event	evt_	Something that happened to a firm, from an open-licensed source.	the index
Decision	dec_	One answer to one named question: p, answer, reason_code, evidence, cost. Immutable.	POST /v1/decisions/<name>
Outcome	out_	What happened after a decision: a bounce, a reply, a booking, an approval.	POST /v1/outcomes
Watch	wch_	A standing request: push me scored events for this ICP above this probability.	POST /v1/watches

Organization and project

An organization owns the balance, the members and the data. Every row Verdict stores for you carries your org id and is isolated by row-level security in the database. A project is a label inside the org. Usage is reported per project, so one org can run several agents and see each one’s spend.

API key

Keys look like vd_live_ plus 43 base62 characters. Test keys start vd_test_; they hit the same API and the same models but draw on a separate, non-cash test balance. A key is shown once when created and never again. Verdict stores only a peppered hash.

Each key carries scopes. The default is decisions:write index:read outcomes:write.

Scope	Grants
decisions:write	Call the priced decisions.
index:read	Read firms, events and sources.
outcomes:write	Report outcomes.
watches:manage	Create, list and delete watches.
vendors:call	Call vendor pass-through (phase 2).
account:read	Read the account, balance, usage, ledger, limits and audit log.
account:manage	Top up and change decision thresholds on ICP profiles.
keys:manage	Create, list, rotate and revoke API keys.

Each key can also have a rate limit, an IP allowlist, a daily spend cap and an expiry. POST /v1/keys/{id}/rotate issues a new secret and keeps the old one valid for a grace window you choose.

ICP profile

An ICP is your description of who you sell to, in plain text, plus optional structured filters (firm_types, size_bands, countries). Verdict summarizes it once when you create it and reuses that summary on every call, so long descriptions do not cost more per decision. Each ICP also holds your thresholds per decision (thresholds); see thresholds.

Firm

A firm is a canonical company in Verdict’s index. You rarely create one. Pass any reference (a domain, a name with a country hint, an LEI, a CIK, a CRD or a Companies House number) and Verdict resolves it. GET /v1/firms/resolve does the same lookup for free when you only need the id and identifiers.

Event

An event is one thing that happened to a firm: a filing, a registration, an officer change, a fund raise. Every event has the same shape whatever its source, with typed attributes per type. Events come only from open-licensed sources; see Data sources.

Event type	Meaning
filing	A regulatory filing; the sub-type is in attributes.filing_type.
registration	A new registration with a registry or regulator.
officer_change	An officer or director was appointed or left.
ownership_change	A change in significant ownership or control.
lei_change	A change to the firm’s LEI record or its parent relationships.
address_change	A change of registered or headquarters address.
fund_raise	A capital raise (for example a Form D offering).
insider_trade	An insider transaction (for example a Form 4).
patent_filing	A patent or trademark filing (phase-2 source).
litigation	A court case involving the firm (phase-2 source).
news_mention	A news mention with citation (phase-2 source).
repo_activity	Organization-level open-source repository activity (phase-2 source).
hiring_aggregate	An aggregate hiring indicator (phase-2 source).

Decision

A decision is the priced unit. You name a question (qualify_firm, score_signal, pick_person, triage_reply, right_person, should_send), Verdict does the lookups underneath, asks its decision model a fixed set of typed questions and returns one envelope:

• p: a calibrated probability, always present.
• answer: p applied to your threshold for that decision. Branch on this one field.
• reason_code: from a fixed list per decision. reason is a short template sentence.
• evidence: sources with URLs and dates.
• calibration: which map produced p and how many outcomes it rests on.
• cost and balance_usd: what you paid and what is left.

calibration.basis	Meaning
org	The organization’s own map (50 or more outcomes for this decision and question-set version).
segment	The map for the ICP’s segment (industry group and size band), pooled from opted-in orgs.
global	The global map, used when neither the org nor the segment has 50 outcomes.

Thresholds are yours to move. Read them on the ICP; change them with PATCH /v1/icps/{id}/thresholds (needs account:manage) to trade precision for recall. Decisions are immutable: GET /v1/decisions/{id} returns the same body forever.

Outcome

An outcome says what happened after a decision. Report it with the decision id. Outcomes are free, unlimited and idempotent. They are how calibration.basis moves from global to segment to org, and how your thresholds tune themselves. See Outcomes and the feedback loop.

Watch

A watch turns the index into a push feed. Give an ICP, an HTTPS URL, a minimum probability and the event types you care about. Verdict scores each new event for your ICP and posts the ones above min_p, signed. Each delivered event bills one score_signal. See Watches and webhooks.