Questions

A request asks 1 to 128 questions about one state. Each question has a name, a type and instructions. A choice or multi_choice adds options, and a score adds levels.

"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?",
    "options": {
      "ato": "Account security / ATO team",
      "aml": "AML investigations",
      "disputes": "Disputes team",
      "none": "No escalation needed"
    }
  }
}

NamesCopy Anchor Link

Each question's key is its name, and its answer comes back under the same name. Names match ^[A-Za-z_][A-Za-z0-9_]{0,63}$: a letter or underscore, then up to 63 letters, digits or underscores. Option keys follow the same pattern.

Question names and option keys are identifiers for your code. The model never sees them, so everything it needs has to be in the instructions and the option descriptions. Naming a question is_ato tells the model nothing.

The four typesCopy Anchor Link

Every question has type and instructions, which must not be blank. Fields that don't belong to the question's type are rejected.

noulCopy Anchor Link

A yes/no question. The answer is P(yes).

{ "type": "noul", "instructions": "Are there signs of account takeover?" }

A noul has no other fields.

choiceCopy Anchor Link

Exactly one option is right. The answer is a distribution over the options that sums to 1.

{
  "type": "choice",
  "instructions": "What is the most likely primary fraud typology?",
  "options": {
    "ato": "Account takeover",
    "synthetic_id": "Synthetic identity",
    "mule": "Money mule activity",
    "first_party": "First-party / bust-out",
    "none": "No fraud indicated"
  }
}

options has 2 to 255 entries of key: description. Descriptions must not be blank and must be unique, ignoring case and whitespace.

multi_choiceCopy Anchor Link

Any number of options can be right. The answer is an independent probability for each option, so the probabilities need not sum to 1.

{
  "type": "multi_choice",
  "instructions": "Which of these fraud typologies are present on this account?",
  "options": {
    "ato": "Account takeover",
    "synthetic_id": "Synthetic identity",
    "mule": "Money mule activity",
    "first_party": "First-party / bust-out",
    "scam": "Authorized push payment scam"
  }
}

options follows the same rules as for choice.

scoreCopy Anchor Link

The answer is a point on an ordered scale. Grayson returns a distribution over the levels, the most likely level and the expected value.

{
  "type": "score",
  "instructions": "How likely is it that this ACH debit will be returned?",
  "levels": ["Very unlikely (under 10%)", "Unlikely (10-40%)", "Uncertain (40-60%)", "Likely (60-90%)", "Very likely (over 90%)"]
}

• levels has 2 to 32 entries, lowest first. Levels must not be blank and must be unique, ignoring case and whitespace.
• values is optional: one number per level, strictly increasing. It defaults to 0, 1, …, K−1 for K levels. See Score values.

Choosing a typeCopy Anchor Link

• Yes or no: noul. "Should this wire be held for review?"
• One right answer: choice. Routing, the next action, the primary typology. A choice puts all of its probability on its options, so when none of them may apply, include an option for that, such as "No escalation needed".
• Several right answers: multi_choice. If two options can both be true, a choice has to split probability between them, and neither may reach 0.5.
• A degree: score. Risk, severity, and every "How likely…" question.

A multi_choice asks about each option separately. With up to 16 options, each one is judged with the full list in view; with more, each is judged on its own, like a separate noul. Use a multi_choice for a family of related labels, such as typologies, and separate noul questions for questions that stand alone.

How likely questionsCopy Anchor Link

Ask "How likely…" questions as scores with ordered likelihood levels. The standard levels are:

["Very unlikely (under 10%)", "Unlikely (10-40%)", "Uncertain (40-60%)", "Likely (60-90%)", "Very likely (over 90%)"]

Using the same levels for every likelihood question keeps answers comparable across questions.

Writing instructionsCopy Anchor Link

• Ask one thing. "Is this account takeover or a scam?" is two questions. Use a choice with both as options, or two noul questions.
• Name the subject. "the outbound ACH on September 20" is clearer than "this" when the state holds several transactions.
• Make yes mean the action. "Should this wire be held?" reads more directly against a threshold than "Is this wire safe to release?"
• Define your own terms. If your team uses a term in its own way, say what it means: "first-party fraud (the account holder disputes transactions they made)".
• Keep the wording fixed. Changing the instructions changes the request and can change the answers. Choose thresholds with the exact wording you run in production.

Writing options and levelsCopy Anchor Link

• Descriptions carry the meaning. Write each description so it stands on its own: "Hold the payment and verify the customer through another channel", not "Hold".
• Order is part of the request. A choice reads its options and a score its levels together, in the order you give them. Keep the same order across requests.
• Make choice options exclusive. If two options can both be true, use multi_choice.
• Put score levels lowest first. values, when you give them, must increase in the same direction.
• No near-duplicates. Descriptions or levels that differ only in case or whitespace are rejected as duplicates.

Score values and the expected valueCopy Anchor Link

Each level has a value: by default 0 for the lowest level, 1 for the next, up to K−1 for the highest. The answer's value is the expected value, the sum of each level's probability times its value.

For example, with the five standard likelihood levels and these probabilities:

• With the default values: 0 × 0.02 + 1 × 0.06 + 2 × 0.25 + 3 × 0.44 + 4 × 0.23 = 2.80.
• With "values": [0, 25, 50, 75, 100]: 0 × 0.02 + 25 × 0.06 + 50 × 0.25 + 75 × 0.44 + 100 × 0.23 = 70.0.

In both cases level is "Likely (60-90%)", the level with the highest probability. values changes only value; probabilities and level stay the same.

The expected value summarizes the whole distribution. To act when an answer is at least "Likely", add up those levels instead: 0.44 + 0.23 = 0.67.

Rules at a glanceCopy Anchor Link

A broken rule returns 400 invalid_request with param pointing at the field. See Errors.