# Developer quickstart (/quickstart)



The API takes JSON over HTTPS (and files as multipart uploads), so any HTTP client works; there's no SDK. Working in an AI agent instead? See the [Agent quickstart](/agent-quickstart).

<Steps>
  <Step>
    ### Get an API key [#get-an-api-key]

    Sign in to the [Finic Portal](https://portal.finic.ai) and create a key under [API keys](https://portal.finic.ai/keys). It starts with `gsk_` and is shown once. Keep it in an environment variable:

    ```bash
    export FINIC_API_KEY=gsk_…
    ```
  </Step>

  <Step>
    ### Ask a question [#ask-a-question]

    Ask works out of the box: send a case's `data` and `context` with your questions, and get a calibrated probability for each answer.

    ```bash
    curl https://api.finic.ai/v1/ask \
      -H "Authorization: Bearer $FINIC_API_KEY" \
      -H "Content-Type: application/json" \
      --data @- <<'EOF'
    {
      "model": "grayson-1",
      "data": {
        "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" }
        ]
      },
      "context": "Customer called at 15:30 to say they can't log in.",
      "questions": {
        "ato": { "type": "noul", "instructions": "Are there signs of account takeover?" }
      }
    }
    EOF
    ```

    `answers.ato.noul` in the response is the probability of yes. See [Questions](/concepts/ask).
  </Step>

  <Step>
    ### Create a scoring model [#create-a-scoring-model]

    Name it and describe the decision: what it is, and what a bad outcome means.

    ```bash
    curl https://api.finic.ai/v1/scoring_models \
      -H "Authorization: Bearer $FINIC_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name": "Card-not-present payment fraud", "criteria": "Card-not-present payments at an online store. Bad: the payment was charged back as fraud within 90 days."}'
    ```

    ```json title="201"
    { "model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9", "request_id": "req_01M4Y7FASG9DB7MMWCS672J0JD" }
    ```

    Creating is free, and it's ready at once, with no questions yet. You can also create it from labeled records in one step; see [Creating a scoring model](/concepts/scoring-models#creating-a-scoring-model).
  </Step>

  <Step>
    ### Calibrate it [#calibrate-it]

    Gather 100+ past records of the decision, 20+ of each outcome, with the fields you send when you score, plus `is_bad` (`true` when the outcome was bad). To try it out, use [sample-payments.csv](/examples/sample-payments.csv), 300 synthetic card payments:

    ```csv title="sample-payments.csv"
    amount_usd,merchant_category,account_age_days,new_device,billing_country,ip_country,is_bad
    2400.00,electronics,19,true,US,NG,true
    58.12,grocery,1260,false,US,US,false
    310.00,gift_cards,3,true,US,US,true
    ```

    ```bash
    curl https://api.finic.ai/v1/calibrate \
      -H "Authorization: Bearer $FINIC_API_KEY" \
      -F model_id=scm_01M4XRC000RT2GZSKYPD8J86G9 \
      -F file=@sample-payments.csv
    ```

    ```json title="202"
    { "job_id": "job_01M4XZXNCRZBPXV30MSF7RN5H3", "rows": 300, "request_id": "req_01M4YPJNK0SZGEQS0A76EEND4N" }
    ```

    Finic writes the scoring model's questions from the records and fits them to your outcomes, for free. Rows can also go in as a JSON array in `data`. See [Labeled records](/concepts/scoring-models#labeled-records) for what to include.
  </Step>

  <Step>
    ### Wait for the job [#wait-for-the-job]

    Calibrating takes about two minutes. Check every 10 seconds or so until `complete` is `true`:

    ```bash
    curl https://api.finic.ai/v1/jobs/job_01M4XZXNCRZBPXV30MSF7RN5H3 -H "Authorization: Bearer $FINIC_API_KEY"
    ```

    ```json title="200"
    { "job_id": "job_01M4XZXNCRZBPXV30MSF7RN5H3", "complete": true }
    ```

    An `error` in the response says what went wrong; see [Get a job](/reference/get-job-status).
  </Step>

  <Step>
    ### Score a record [#score-a-record]

    Send a record with the same fields, and your own unique `score_id` for it:

    ```bash
    curl https://api.finic.ai/v1/score \
      -H "Authorization: Bearer $FINIC_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9", "score_id": "pay_88213", "data": {"amount_usd": 1850.0, "merchant_category": "electronics", "account_age_days": 6, "new_device": true, "billing_country": "US", "ip_country": "RO"}}'
    ```

    ```json title="200"
    { "model_id": "scm_01M4XRC000RT2GZSKYPD8J86G9", "score_id": "pay_88213", "score": 874, "request_id": "req_01M4YF1068X8B4C458ENPD4JHT" }
    ```

    874 means about an 87% chance of a bad outcome: the scoring model is calibrated, so its scores are about the chance of a bad outcome, and you can choose thresholds on them. [`GET /v1/scoring_models/{model_id}`](/reference/get-scoring-model) shows its questions, and [`add_questions`](/reference/add-questions) adds your own. Records you score must have the fields of the calibration's records; see [Schema](/concepts/scoring-models#schema).

    Want to score before you have labeled records? [Add your own questions](/reference/add-questions) to the new scoring model: it scores with them right away, weighed by Finic's estimates, until you calibrate it.
  </Step>

  <Step>
    ### Keep it calibrated [#keep-it-calibrated]

    As you learn how more records turned out, calibrate again with a fresh set of labeled records, the same way. Each calibration is free and chooses again which questions to use. See [Calibration](/concepts/calibration#calibrate-a-scoring-model).
  </Step>
</Steps>

Log the `X-Request-Id` header of every response; support asks for it.

## The whole flow in Python [#the-whole-flow-in-python]

```python
import os
import time

import requests

API = "https://api.finic.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['FINIC_API_KEY']}"}


def check(r: requests.Response) -> dict:
    if not r.ok:
        e = r.json()["error"]
        raise RuntimeError(f"{r.status_code} {e['type']}: {e['message']} (request {r.headers.get('X-Request-Id')})")
    return r.json()


def wait_for(job_id: str) -> None:
    while not (job := check(requests.get(f"{API}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)))["complete"]:
        time.sleep(30)
    if "error" in job:
        raise RuntimeError(f"{job['error']['type']}: {job['error']['message']}")


created = check(requests.post(f"{API}/v1/scoring_models", headers=HEADERS, timeout=60,
                              json={"name": "Card-not-present payment fraud",
                                    "criteria": "Card-not-present payments. Bad: charged back as fraud within 90 days."}))

# Fit it to your data with labeled records:
with open("sample-payments.csv", "rb") as f:
    calibration = check(requests.post(f"{API}/v1/calibrate", headers=HEADERS, timeout=60,
                                      data={"model_id": created["model_id"]}, files={"file": f}))
wait_for(calibration["job_id"])

record = {"amount_usd": 1850.0, "merchant_category": "electronics", "account_age_days": 6,
          "new_device": True, "billing_country": "US", "ip_country": "RO"}
scored = check(requests.post(f"{API}/v1/score", headers=HEADERS, timeout=60,
                             json={"model_id": created["model_id"], "score_id": "pay_88213", "data": record}))
print(scored["score"])
```

Every endpoint in the [API reference](/reference) has a playground that sends requests from the docs.
