Quickstart

This page is the fifteen-minute path. Every step is one HTTP call. No browser and no card are needed. Total cost: one qualify_firm answer, $0.005, paid from the $5 starter credit.

You need curl, uuidgen and jq. All requests go to https://api.askverdict.io/v1.

Send your email. Verdict emails a verification link. Free.

curl -X POST 'https://api.askverdict.io/v1/signup' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "org_name": "Your Company"}'

The response is 202 with status and expires_at. Disposable email domains are refused.

2. Verify and receive your key

The email contains a token. Exchange it for your organization, your first project and your first API key. Free.

curl -X POST 'https://api.askverdict.io/v1/signup/verify' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"token": "TOKEN_FROM_THE_EMAIL"}'

The response carries secret, shown once and never again, and starter_credit_usd of $5. Store the secret now:

export VERDICT_API_KEY='vd_live_...'

The key has the default scopes decisions:write, index:read and outcomes:write. That is enough for everything below.

3. Describe who you sell to

An ICP profile is plain text plus optional filters. Every decision is made against one. Free.

ICP_ID=$(curl -s -X POST 'https://api.askverdict.io/v1/icps' \
  -H "Authorization: Bearer $VERDICT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"name": "RIAs under $1B", "description": "US registered investment advisers with under $1B in assets and fewer than 50 staff. We sell trade reconciliation software to their operations lead.", "filters": {"firm_types": ["investment_adviser"], "size_bands": ["micro", "small"], "countries": ["US"]}}' \
  | jq -r .id)
echo "$ICP_ID"

The response is the Icp with its id (icp_...).

4. Make the first decision

Ask whether a firm is in your ICP. Give a domain and the ICP id. $0.005, billed only when an answer comes back.

curl -X POST 'https://api.askverdict.io/v1/decisions/qualify_firm' \
  -H "Authorization: Bearer $VERDICT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'X-Max-Cost-USD: 0.01' \
  -H 'Content-Type: application/json' \
  --data @- <<EOF
{"firm": {"domain": "northfieldcapital.com"}, "icp_id": "$ICP_ID"}
EOF

What comes back (abridged):

{
  "id": "dec_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "decision": "qualify_firm",
  "p": 0.82,
  "answer": "fit",
  "reason_code": "icp_type_and_size_match",
  "firm": { "id": "frm_01JC3Z4Y8R9K2M5N7P1Q3S5T7V", "name": "Northfield Capital Advisors LLC" },
  "calibration": { "basis": "org", "n_outcomes": 412, "threshold": 0.6 },
  "cost": { "decision_usd": 0.005, "vendor_usd": 0, "total_usd": 0.005 },
  "balance_usd": 4.995
}

Branch on answer (fit or not_fit). Keep id: it links the outcome in the next step. The full response is on qualify_firm.

5. Report what happened

When you learn the result (a reply, a booking, a skip), report it. Outcomes are free and move your thresholds.

curl -X POST 'https://api.askverdict.io/v1/outcomes' \
  -H "Authorization: Bearer $VERDICT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"decision_id": "dec_01JC3Z4Y8R9K2M5N7P1Q3S5T7V", "outcome": "approved", "observed_at": "2026-11-09T16:30:00Z"}'

6. Check your balance

curl 'https://api.askverdict.io/v1/balance' \
  -H "Authorization: Bearer $VERDICT_API_KEY"

GET /v1/balance needs the account:read scope. Your first key does not have it by default; every billed response already carries balance_usd. When credit runs low, POST /v1/topup returns a Stripe Checkout URL for a $20, $50 or $200 pack.

Then use the SDK

The same flow in TypeScript and Python. The SDKs add typed responses, retries with backoff on 429 and 5xx, idempotency keys by default, a max_cost option and outcome helpers.

import { Verdict } from "@verdict/sdk";

const verdict = new Verdict(); // reads VERDICT_API_KEY
const icp = await verdict.icps.create({
  name: "RIAs under $1B",
  description: "US registered investment advisers with under $1B in assets.",
});
const decision = await verdict.decisions.qualifyFirm({
  firm: { domain: "northfieldcapital.com" },
  icp_id: icp.id,
});
if (decision.answer === "fit") await verdict.approve(decision.id);

from verdict import Verdict

verdict = Verdict()  # reads VERDICT_API_KEY
icp = verdict.icps.create({"name": "RIAs under $1B", "description": "US RIAs under $1B in assets."})
decision = verdict.decisions.qualify_firm(
    {"firm": {"domain": "northfieldcapital.com"}, "icp_id": icp.id}
)
if decision.answer == "fit":
    verdict.approve(decision.id)

Or from a terminal: verdict signup [email protected], verdict verify <token>, then verdict decide qualify_firm --domain northfieldcapital.com --icp <icp_id>.