Finic
ContactTry the API
Claims and customer contacts

Fraud typology classification

Grayson labels a fraud claim with a FraudClassifier class, a ScamClassifier type and contributing factors, and decides reimbursement, from the claim file: statements, payments, account history and session logs.

Grayson classifies a fraud or scam claim with the categories of the Federal Reserve's FraudClassifier and ScamClassifier models (who initiated the payment and how, which type of scam, and which contributing factors were present) and answers whether the law and your reimbursement policy call for repaying the customer. It reads the claim file (the customer's statement and interview notes, each payment with how it was initiated, months of account history and the session logs around the events) and costs about $0.53 to $0.71 per 1,000 decisions.

  • Decides: Label a fraud claim with a FraudClassifier class, scam type and contributing factors; decide reimbursement.
  • Call it: When a fraud claim has the customer's statement and payment records
  • Questions: 2 choice, 1 multiple choice, 1 yes/no
  • Cost: $0.00053 to $0.00071 per decision ($0.53 to $0.71 per 1,000) for these examples' 15,214 to 20,264 input tokens
  • Latency: 249 to 288 ms for these examples, the median of 5 calls each through api.finic.ai from US-West

Examples

Three claims at a credit union, each with six months of account history, 90 days of digital-banking sessions, call summaries and the payments: a bank impostor scam in which a member wired her savings from a branch, a self-employed member reporting his own scheduled IRS payment as fraud, and a refund scam over remote access where it's unclear whether the member or the caller sent the P2P payment.

Open in Playground

Open in Playground

Open in Playground

A yes/no answer is Grayson's probability that it's true. A choice answer is the top option and Grayson's confidence: 0% when every option is equally likely, 100% when one option has all the probability. A score answer is the expected level, numbering the levels in its criteria from 0, with its confidence measured the same way and, when no level reaches 70%, each level's probability. A multiple-choice answer lists the options at 50% or more.

  • fraud_classifier and scam_type: record the top option when it's high and well ahead of the runner-up; send close calls to an analyst.
  • contributing_factors returns a probability per factor; its eight options cost more tokens than the other three questions together, so trim to those you report on.
  • reimburse is the probability that it's true: send likely reimbursements to payout and the rest to an analyst, and keep a person responsible for every denial. A middle probability, as in the remote-access claim, usually means it's unclear who sent the payment.

Call it from your code

Save an example as request.json, such as fraud.json, and send it with your API key in GRAYSON_API_KEY:

curl https://api.finic.ai/v1/decide \
  -H "Authorization: Bearer $GRAYSON_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

The problem

The hardest call is authorization, and one claim often contains both kinds: a payment a scammer sent with a code the customer read out, and a wire the customer was talked into sending. The facts that separate them sit in free text next to device and authentication records, which is why rules based on payment type alone get it wrong.

What to send

Send the claim and its records, naming one payment per call as payment_under_review:

  • How each payment was initiated. Device, session, codes and whether the customer was present answer the authorized-or-unauthorized question.
  • The customer's statement, verbatim. The deception it describes defines the ScamClassifier type.
  • Sign-ins, devices, codes and session signals. A new device signing in minutes after a code went to the customer points to credentials given away; a remote-access signal on the customer's own device raises the question of who was in control.
  • Staff notes from the payment. A stated purpose that doesn't fit the beneficiary suggests coaching.
  • Account history, recipient history and timeline. Months of activity show what's normal for the customer, such as earlier payments to the same payee or money moved between their own accounts beforehand. A first-ever recipient stands out, and the reporting date drives Regulation E liability and policy windows.
  • Recovery steps. Recalls and network fraud reports change what's left to repay, not the class.

Add your own policy

US law doesn't require you to repay a wire the customer sent themselves, but many institutions repay some scam losses under written conditions, which Grayson applies when they're in the request. This one repays impostor scams up to $10,000 when the member reports within three business days and hasn't been repaid before, and excludes members who gave staff false information unless the impostor told them what to say.

Your scam reimbursement policy adds this to the state of the obvious example:

{
  "reimbursement_policy": "Impostor scam reimbursement (effective 2026-07-01). We reimburse a member who was deceived into sending a payment by someone impersonating our credit union, another financial institution or a government agency, up to $10,000 per member in any 12 months, less any amount recovered, when all of these are true: (1) the member reports the scam within 3 business days of the payment; (2) the member has not received a scam reimbursement in the past 24 months; (3) the member did not give our staff false information to complete the payment, unless the impersonator told them what to say. The policy covers wires, P2P payments and online transfers that the member sent. Transfers someone else made from the member's account are handled as unauthorized transfers under Regulation E, not under this policy."
}
QuestionWithoutWith your scam reimbursement policy
fraud_classifiermanipulated_relationship_trust, confidence 85%manipulated_relationship_trust, confidence 86%
scam_typebank_impostor, confidence 96%bank_impostor, confidence 98%
contributing_factorsunsolicited_contact, credentials_phished, code_shared, new_device, new_recipient, coached, pressureunsolicited_contact, credentials_phished, code_shared, new_device, new_recipient, coached, pressure
reimburse13% true97% true

Applied to the bank impostor example: the member reported the day after the wire, has no earlier scam reimbursement, and told the teller and branch manager what the caller told her to say, so the policy covers the $8,400 wire and reimburse flips to yes while the classes stay the same.

Where to call it

  • Once the statement and payment records are attached, usually at the end of the intake call, and once per payment with a different payment_under_review.
  • Unauthorized transfers go to your Regulation E error-resolution process: generally 10 business days to investigate, or 45 days if you give provisional credit.
  • Uncertain answers go to an analyst; call again when new facts arrive, such as the receiving bank's reply to a recall.

Cost and latency

ExampleInput tokensPer decisionPer 1,000 decisionsLatency
Obvious20,248$0.00071$0.71288 ms
Legitimate20,264$0.00071$0.71274 ms
Ambiguous15,214$0.00053$0.53249 ms

You pay only for input tokens, at $0.035 per million, and each request is rounded up to the next millionth of a dollar, so a request with a larger state costs proportionally more; every response reports its size in usage.input_tokens. Latency is the median of 5 calls each through api.finic.ai from US-West, and grows with the number of input tokens. Add your own network time to api.finic.ai.

Evaluate on your own data

Score Grayson on your own past cases before you use it: a CSV with one row per case and a column with the right answer to each question. Every other column is sent as the case.

pipx install https://docs.finic.ai/downloads/grayson_cli-0.4.0-py3-none-any.whl
grayson eval my-cases.csv --questions https://docs.finic.ai/recipes/fraud-scam-classification/questions.json --label fraud_classifier=<column> --label scam_type=<column> --label contributing_factors=<column> --label reimburse=<column>

Each --label names the column with that question's right answer:

  • fraud_classifier: manipulated_products_services, manipulated_relationship_trust, acted_embezzlement, acted_false_claim, acted_synthetic_id, modified_compromised_credentials, modified_impersonation, modified_physical_alteration, takeover_compromised_credentials, takeover_impersonation, misused_digital, misused_physical_counterfeit, not_fraud
  • scam_type: merchandise, investment, property_sale_rental, romance_impostor, government_impostor, bank_impostor, business_impostor, relative_family_friend, other_trusted_party, not_scam
  • contributing_factors: option keys separated by | (unsolicited_contact, credentials_phished, code_shared, remote_access, new_device, new_recipient, coached, pressure)
  • reimburse: true or false

Or run grayson on its own to set up your questions step by step. You get each question's accuracy and a CSV with Grayson's answer next to yours for every case.

Evaluate on your own data

How it works, what you get, and every option.

FAQ

Is a scam always an authorized payment?

No. The ScamClassifier model also counts scams that end in unauthorized payments, and the CFPB's Regulation E FAQs say that when a third party tricks a consumer into sharing account access information, such as a texted code, and uses it to make a transfer, the transfer is unauthorized. In this recipe's bank impostor example, the P2P payment is a FraudClassifier account takeover with compromised credentials and the wire is relationship and trust fraud; both are bank impostor scams.

Can I use my own taxonomy instead of the Federal Reserve's?

Yes. The options are plain text, so replace them with your own categories and definitions, or ask both in one request, and keep the wording fixed once you've chosen thresholds. Grayson isn't affiliated with or endorsed by the Federal Reserve; the questions in this recipe paraphrase the models' definitions.

Can it spot a false claim dressed up as a scam?

The FraudClassifier question includes the false claim class, which competes with the others on the evidence, such as payments from the customer's own trusted device to a recipient they've paid before, or a statement that contradicts the device and authentication records. Grayson returns a probability, not a finding, so send claims with a high false-claim probability to an investigator, who documents the decision.

Classify card disputes and detect friendly fraud

Classify unauthorized-transaction claims and choose provisional credit, approval or denial.

Detect business email compromise in vendor payments

Catch payments to a vendor's new bank account after a fake or compromised change request.

Recipes

Every use case, with its questions and cost per decision.

Contact triage

Grayson reads a call transcript, chat or secure message with the account's recent sign-ins, payments and contacts, and decides what it's about, whether to freeze now, where to route it and whether the customer is vulnerable.

State

What to put in the state, the formats Grayson accepts, and how the state counts toward the token limit.

On this page

ExamplesCall it from your codeThe problemWhat to sendAdd your own policyWhere to call itCost and latencyEvaluate on your own dataFAQIs a scam always an authorized payment?Can I use my own taxonomy instead of the Federal Reserve's?Can it spot a false claim dressed up as a scam?Related recipes