Finic
ContactTry the API
Recipes

Fraud typology classification

Grayson labels a fraud claim with a FraudClassifier class, a ScamClassifier type and contributing factors, and decides reimbursement, from notes and payments.

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 case notes, the customer's statement and each payment with how it was initiated, and costs about $0.13 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.00013 per decision, $0.13 per 1,000, for this example's 3,756 input tokens
  • Latency: 214 ms for this example, the median of 5 calls through api.finic.ai from US-West

Example

A credit union member read out two codes to a caller posing as the credit union's fraud department, who used them to send a $2,850 P2P payment from a new device, then talked her into wiring $7,500 to a "holding account" from her branch; the request classifies the wire.

Open in PlaygroundEdit and run this request in the Finic portal.
QuestionGrayson's answer
fraud_classifiermanipulated_relationship_trust, 74%
scam_typebank_impostor, 96%
contributing_factorsunsolicited_contact, credentials_phished, code_shared, new_device, new_recipient, coached, pressure
reimburseNo, P(yes) 6%

Each percentage is Grayson's probability for the answer shown; for a yes/no question it's the probability of yes. 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 P(yes): send likely reimbursements to payout and the rest to an analyst, and keep a person responsible for every denial.

Call it from your code

Save request.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 and codes. A new device signing in minutes after a code went to the customer points to credentials given away.
  • Staff notes from the payment. A stated purpose that doesn't fit the beneficiary suggests coaching.
  • Recipient history and timeline. 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 criteria

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 context:

{
  "reimbursement_policy": "Impostor scam reimbursement (Harbor Federal Credit Union, effective 2026-07-01). We reimburse a member who was deceived into sending a payment by someone impersonating Harbor Federal, 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 Harbor Federal 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, 74%manipulated_relationship_trust, 84%
scam_typebank_impostor, 96%bank_impostor, 96%
contributing_factorsunsolicited_contact, credentials_phished, code_shared, new_device, new_recipient, coached, pressureunsolicited_contact, credentials_phished, code_shared, new_device, new_recipient, coached, pressure
reimburseNo, P(yes) 6%Yes, P(yes) 95%

The member reported the day after the wire, has no earlier reimbursement, and told the teller what the caller instructed her to say, so the policy covers the wire and reimburse should flip 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

This example is 3,756 input tokens, so a decision costs $0.00013: $0.13 per 1,000 decisions, or $132.00 per million. You pay only for input tokens, at $0.035 per million, and each request is rounded up to the next millionth of a dollar. A larger context costs proportionally more; every response reports its size in usage.input_tokens.

Grayson answered this example in 214 ms, the median of 5 calls through api.finic.ai from US-West. Latency 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.2.2-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 claim, 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.

Dark web alerts

Grayson triages dark web alerts: whether a leaked password, bank log or card listing matches a customer, whether it still works, and what to do about it.

Incoming payments

Decide whether an incoming ACH credit is the proceeds of fraud at the sender, and whether to release, hold or return it, from account, login and transfer data.

On this page

ExampleCall it from your codeThe problemWhat to sendAdd your own criteriaWhere 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