Questions

An ask request asks 1 to 128 questions about one case, its data and context. Grayson, Finic's decision model, answers each with calibrated probabilities. Nothing is generated: no rationale or text, only probabilities.

"questions": {
  "is_fraud": { "type": "noul", "instructions": "Is this account engaged in or the victim of fraud?" },
  "escalate_to": {
    "type": "choice",
    "instructions": "Which team should this alert be escalated to?",
    "criteria": { "ato": "Account security / ATO team", "aml": "AML investigations", "none": "No escalation needed" }
  }
}

Each question's key names it, and its answer comes back under the same key. Keys and option keys match ^[A-Za-z_][A-Za-z0-9_]{0,63}$. The model never sees them: everything it needs goes in the instructions and criteria. In a choice, the key (ato) comes back in the answer; the description ("Account security / ATO team") is what the model reads.

Question typesCopy Anchor Link

Every question has type and instructions (not blank). Fields that don't belong to the type are rejected. Every answer repeats its question's type.

"answers": {
  "is_fraud": { "type": "noul", "noul": 0.92 },
  "primary_typology": { "type": "choice", "choice": "ato", "confidence": 0.85, "probabilities": { "ato": 0.88, "synthetic_id": 0.02, "mule": 0.05, "first_party": 0.03, "none": 0.02 } },
  "typologies_present": { "type": "multi_choice", "multi_choice": ["ato", "mule"], "probabilities": { "ato": 0.93, "synthetic_id": 0.04, "mule": 0.61, "first_party": 0.03, "scam": 0.07 } }
}

• Option descriptions must not be blank and must be unique, ignoring case and whitespace. A null description reads as the key with spaces for underscores (first_party reads "first party"), but a real description works better.
• A choice spreads all its probability over its options, so include one for "none of these" when that can happen. If two options can both be true, use multi_choice: a choice has to split probability between them, and neither may reach 0.5.
• A multi_choice asks about each option separately. With up to 16 options, each is judged with the full list in view; with more, each on its own, like a separate noul.

ConfidenceCopy Anchor Link

A choice's confidence is (K × the top probability − 1) / (K − 1) over K options: 0 when all are equally likely, 1 when one has all the probability. In the answers above, (5 × 0.88 − 1) / 4 = 0.85.

choice and multi_choice summarize the probabilities; base decisions on the probabilities themselves, unrounded. See Choosing thresholds.

Writing good questionsCopy Anchor Link

• Ask one thing. "Is this account takeover or a scam?" is two questions: use a choice, or two nouls.
• Name the subject: "the outbound ACH on September 20", not "this", when the data holds several transactions.
• Make yes mean the action: "Should this wire be held?" thresholds more directly than "Is this wire safe to release?"
• Define your terms and standards. "High risk: two or more of a new device, a new payee and a changed email in the last 24 hours" gets answers that follow your policy; "High risk" leaves it to the model.
• Write descriptions that stand alone: "Hold the payment and verify the customer another way", not "Hold".
• Keep wording and order fixed. A choice reads its options together, in the order given. Changing the wording or order can change the answers, so choose thresholds with the exact questions you run in production.
• Ask about signals directly when you need to record why: "Did the account log in from a new device shortly before the transfer?" gives a probability you can log and show a reviewer.

Determinism and isolationCopy Anchor Link

• The same request always gets the same answers, so retrying is safe. Any change (instructions, option order, data, context, key order) makes it a different request. Whitespace between JSON tokens in data doesn't matter; whitespace inside strings does.
• Each question sees only the case and its own text, never the other questions: adding, removing or renaming one can't feed into another's answer. Numerical rounding can still move other answers slightly, under 1 percentage point on average.

Requests and answers are kept only as your data retention allows. To keep them for audits, appeals or threshold tuning, store the request and response, with its id and request_id, with your own decision record.