The decision envelope
Every POST /decide answer has the same top-level fields. Branch on decision; read result for the details of each capability.
| Field | Type | Meaning |
|---|---|---|
id |
string | Decision id (dec_…). Use it for feedback, evidence and Ask |
object |
"decision" |
|
model |
string | The release that answered, e.g. ward-1.4.6 |
components |
object | Version of each part that ran (screening, statement_matrix, …) |
type |
string | The decision type |
created |
integer | Unix time |
decision |
APPROVE | STEP_UP | DECLINE |
What to do |
score |
number | null | The capability's score (0–1) |
score_kind |
string | null | What the score is: calibrated, heuristic, name_similarity, kya, … See Scores |
band |
string | low / medium / high for statement, credit and merchant |
signals |
string[] | Codes of what fired, e.g. STM_PASS_THROUGH, EMAIL_DISPOSABLE |
typologies |
string[] | Typology ids the signals point to (fraud and AML catalogs) |
needs |
object[] | Fields not sent that would sharpen the answer, each with why |
coverage |
object | How much of the input Ward could read (sufficient, limited, insufficient) |
subject |
object | null | The customer's profile when subject_ref is known |
session_id |
string | null | Echo |
result |
object | The capability's full native answer |
client_model |
object | Your account's trained model, advisory (see Feedback) |
policy_matches |
object[] | Your own policies the case touches (cited, never applied) |
review_sample |
boolean | Marked for random review (selection-bias control) |
context |
object | The session meter: window_tokens, used_tokens, remaining_tokens, used_pct, balance_usd |
latency_ms, timing |
number, object | Total time and inference time |
Reading result
Each capability page documents its result. Fields common to several:
checks: which lists ran and their status (checked,not_checked,failed). "No hits" withnot_checkedis not clear.notes: assumptions Ward made (date order, currency, a column it guessed).signalsinsideresult: full objects withcode,weight,detailand the rows they cite; the envelope'ssignalsis the list of codes.
Fields the client model adds
When your validated model sets the decision (see Feedback), the envelope also carries:
| Field | Meaning |
|---|---|
decided_by |
client_model |
decision_rules, score_rules |
What the rules decided and scored, kept for audit |
hard_stops |
Signals that kept the stricter of the two decisions (strong sanctions match, device or IP linked to fraud, invalid cryptogram, ATC replay) |
review_floors |
Signals that kept the decision at STEP_UP or above (a potential sanctions match, a high-risk jurisdiction) |
Risk lines (Ward 1.5, beta)
Off by default; enabled per deployment. With it on, the answer adds typed answers per risk and changes no existing field.
| Field | Type | Meaning |
|---|---|---|
risks.fraud, risks.aml, risks.sanctions |
object | One entry per risk the call assessed. A payment has fraud, and sanctions for bank transfers; a statement has aml, fraud and sanctions; a screen has sanctions |
risks.<line>.status |
final | partial | insufficient_data |
Whether the line could answer. partial: only part of the evidence was readable on this call (on a bank transfer, AML shows the payee's jurisdiction only). insufficient_data is never a clear result |
risks.<line>.review_floors, hard_stop |
string[], boolean | What on this line keeps the decision at STEP_UP or above, or declines it |
risks.<line>.outcome |
Choice | The line's own answer, for example {"type": "choice", "choice": "strong_match"}. A reference-calibrated card fraud line adds probabilities per option and confidence: how sure Ward is that the case sits on the chosen side of each cut-off. The choice always comes from the cut-offs; a near-even split marks a close call |
risks.<line>.raw_score |
number | null | The line's score before any calibration |
risks.<line>.p, interval |
number | null, [low, high] | A probability when score_kind is calibrated or reference_calibrated, with a 90% interval for the latter. null for a heuristic score with no reference map |
risks.<line>.calibration |
object | For reference_calibrated: set, simulated, heldout_ece, reference_rate, prior and prior_source (default or client), the block's cases and bad, and the map hash |
risks.<line>.score_kind, evidence_tier, advisory |
How far the score can be read (see Scores) | |
risks.<line>.signals, typologies |
string[], object[] | What fired on this line; each typology with its catalog domain (agentic, card, crypto, financial) |
risks.<line>.gates |
boolean | Whether this line can move decision |
risks.aml.priority |
Score | AML review priority: clear, monitor, alert, escalate (cuts 0.30, 0.60, 0.80 on the line's raw score), with level probabilities when the line is reference-calibrated. On a payment it needs account.movements (10 or more over 30 days or more); with_this_payment lists the signals the payment itself brings. Advisory: gates is false |
outcome |
Choice or Score | For screen, statement, ato and agent: the answer in the type's own words (potential_match, the statement band as a level 0 to 2, likely_account_takeover, verified_with_flags) |
answers |
object | Yes or no questions answered on the call, as Nouls: {"type": "noul", "noul": 0.08} is the probability of yes. First-party misuse and takeover when their models are on, and the questions you sent |
risks.fraud.typology |
Choice | On payments: the typology as a walk down the catalogs (path: domain, family, typology), one level of probabilities per step, the first scaled by the line's probability (none is the rest). Shares of signal strength, not a calibrated distribution |
not_assessed |
object[] | Risks this call could not judge, each with why. A single payment has no AML reading; a card payment is not screened |
initiator, treatment |
object | For payments: who initiated it, and what to do when a scam leads (also in result) |
decision_ward_1, aml_gated |
string, boolean | With model: "ward-2" only: what ward-1 would have decided when the two differ, and whether the AML line set the decision (see Models) |
Stability
Field names are stable within a major version. New fields can appear at any time; ignore what you do not know. Pin model to a release to keep thresholds and weights fixed (see Models).