# Introduction (/)



Grayson answers questions about fraud and risk cases with probabilities. You send a **state**, everything you know about a case, and a set of named, typed **questions**. Grayson returns a calibrated probability for every possible answer. Nothing is generated: there is no rationale or free text, only numbers you can threshold, rank and log.

Model `grayson-1` · Base URL `https://api.finic.ai` · Endpoint `POST /v1/decide`

```json title="Request"
{
  "model": "grayson-1",
  "state": {
    "events": [
      { "ts": "2026-09-14T15:02:11Z", "type": "sim_change" },
      { "ts": "2026-09-14T15:09:40Z", "type": "login", "new_device": true },
      { "ts": "2026-09-14T15:12:03Z", "type": "p2p_out", "amount_usd": 2400.0, "payee_added": "2026-09-14T15:11:20Z" }
    ]
  },
  "questions": {
    "ato": { "type": "noul", "instructions": "Are there signs of account takeover?" }
  }
}
```

```json title="Response"
{
  "id": "dec_01J9QK2V7R4TBX8M3N5P6Q7R8S",
  "model": "grayson-1",
  "answers": {
    "ato": { "type": "noul", "noul": 0.9137 }
  },
  "usage": { "input_tokens": 143, "output_tokens": 0 },
  "request_id": "req_01J9QK2V7Q2M8D4F6H1K3N5P7R",
  "evaluation_time_ms": 96.2
}
```

## How a decision works [#how-a-decision-works]

1. **Describe the case.** Put account records, events, transactions and notes in `state`, as JSON or plain text. There is no schema. See [State](/concepts/state).
2. **Ask typed questions.** Give each question a name, a type and instructions, up to 128 per request. See [Questions](/concepts/questions).
3. **Read the probabilities.** Each answer comes back under its question's name. Apply your own thresholds and act. See [Answers and probabilities](/concepts/answers).

The same request always returns the same answers. Each question is answered on its own: questions never see each other.

## Choose a question type [#choose-a-question-type]

| Type           | Use it when                                                                       | Example                                                  | You get                                                               |
| -------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------- |
| `noul`         | The answer is yes or no                                                           | "Are there signs of account takeover?"                   | The probability that it's true                                        |
| `choice`       | Exactly one option is right                                                       | "Which team should this alert be escalated to?"          | A distribution over the options that sums to 1                        |
| `multi_choice` | Any number of options can be right                                                | "Which of these fraud typologies are present?"           | An independent probability for each option                            |
| `score`        | The answer is a point on an ordered scale, including every "How likely…" question | "How likely is it that this ACH debit will be returned?" | The expected level, its confidence and a distribution over the levels |

## Try it in the portal [#try-it-in-the-portal]

The [portal playground](https://portal.finic.ai/playground) has 10 synthetic cases you can run and edit before you write code: account takeover after a SIM change, a P2P scam during a phone call, business wires into a new account, an onboarding review, ACH returns, merchant transaction laundering, a card dispute, a wire release, a crypto withdrawal and a merchant website scan.

## Start here [#start-here]

<Cards>
  <Card title="Quickstart" href="/quickstart" description="Create an API key and make your first decision with curl, Python or TypeScript." />

  <Card title="Questions" href="/concepts/questions" description="The four question types, and how to write instructions and criteria." />

  <Card title="Create a decision" href="/reference/decide" description="Every request and response field of POST /v1/decide." />

  <Card title="Errors" href="/reference/errors" description="Error types, what causes each one and which to retry." />
</Cards>