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?" }
}
}
EOFanswers.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,truecurl 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.
Introduction
Finic gives calibrated risk scores and answers for fraud and risk, calibrated to your own fraud rates. Two endpoints, score and ask.
Agent quickstart
Add Finic's MCP server to Claude, ChatGPT, Cursor or any MCP client. Your agent signs you in, sets up Finic with you, asks questions and scores records.