Developer quickstart

Get an API key, ask a question, then create a scoring model, calibrate it with labeled records and score a record.

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.

Get an API key

Sign in to the Finic Portal and create a key under API keys. It starts with gsk_ and is shown once. Keep it in an environment variable:

export FINIC_API_KEY=gsk_…

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.

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.

Create a scoring model

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

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."}'
{ "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.

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, 300 synthetic card payments:

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
curl https://api.finic.ai/v1/calibrate \
  -H "Authorization: Bearer $FINIC_API_KEY" \
  -F model_id=scm_01M4XRC000RT2GZSKYPD8J86G9 \
  -F file=@sample-payments.csv
{ "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 for what to include.

Wait for the job

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

curl https://api.finic.ai/v1/jobs/job_01M4XZXNCRZBPXV30MSF7RN5H3 -H "Authorization: Bearer $FINIC_API_KEY"
{ "job_id": "job_01M4XZXNCRZBPXV30MSF7RN5H3", "complete": true }

An error in the response says what went wrong; see Get a job.

Score a record

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

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"}}'
{ "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} shows its questions, and add_questions adds your own. Records you score must have the fields of the calibration's records; see Schema.

Want to score before you have labeled records? Add your own questions to the new scoring model: it scores with them right away, weighed by Finic's estimates, until you calibrate it.

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.

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

The whole flow in 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 has a playground that sends requests from the docs.

On this page