Data & context

A decide request describes a case in two fields. Send either, or both:

• data: structured data as JSON: account records, events, transactions, an alert, an application. A string also works, read as sent (CSV text, for example).
• context: free text: analyst notes, customer messages, emails, documents.

There's no schema: send records in the shape you keep them. Every question in the request is answered from the same data and context; with both, the data is read first. A record sent to POST /v1/score also goes in data, in the shape of the score's examples.

"data": {
  "dispute": { "filed": "2026-09-21", "amount_usd": 612.40, "merchant_category": "electronics", "transaction_date": "2026-09-12" },
  "authorization": { "entry_mode": "chip", "cvm": "pin_verified" }
},
"context": "Cardholder called on 9/21: says the charge wasn't theirs and the card was never lost. Their son also has access to the account."

A blank string, or a number, boolean or null on its own, is rejected. A decide request with neither field fails with 400 invalid_request (param: data).

What to includeCopy Anchor Link

What a reviewer would look at:

• The customer or account: tenure, KYC and verification results, contact details and when they changed, earlier alerts.
• Recent activity: logins, device and IP changes, profile changes, payments and transfers.
• The item under review: the transaction, application, dispute or withdrawal, with amounts, counterparties and timestamps.
• Case notes: rule hits, analyst notes, customer messages, usually in context.

Only include what was known when the decision was made: when you replay past cases, cut each at the time of the decision. Leave out what can't matter: passwords, full card numbers and one-time codes never help.

Make it readableCopy Anchor Link

• Order matters. data is read as compact JSON in the key order you send. Put events in time order and keep related fields together. Python dicts and JavaScript objects keep insertion order (JavaScript moves integer-like keys such as "2024" first); Go's encoding/json sorts map keys; Java's HashMap has no order (LinkedHashMap keeps it).
• Name fields in words (amount_usd, not amt), give units and currencies, and use ISO 8601 timestamps with Z or an offset.
• Expand your own codes: "rule": "R-417: 3 failed logins, then a password reset", not "rule": "R-417".

Text in data or context that looks like a question or an instruction is read as part of the case: question boundaries use reserved tokens no input can produce. Customer-written text, such as a dispute narrative, can go in as it is.

SizeCopy Anchor Link

data, context and the questions share decide's limit of 32,768 tokens per request; each response reports the total in usage.input_tokens. JSON is compacted first, so whitespace between keys costs nothing. Over the limit, the request fails with 413 request_too_large, giving its size. To fit a long history, send a recent window, drop fields your questions never need, or summarize older events. See How tokens are counted.

Data retentionCopy Anchor Link

How long Finic keeps the content of requests (data, context, questions and answers) has two layers:

• Your organization's setting, chosen by its admins: Zero Data Retention (nothing is kept) or 7, 30, 90 or 365 days. Kept requests can be opened by the organization's members from Usage in the Finic Portal.
• Your own setting, for your account across all your organizations. It can only make retention stricter. It covers requests you make: in the playground, and through API keys, docs sign-ins and agent sign-ins you created.

A request is kept for the shorter of the two, and Zero Data Retention always wins. Choosing a shorter period deletes content already kept beyond it. Set yours in the Finic Portal under Settings → Account, or have your agent use set_data_retention; admins set the organization's under Settings → Organization.

Score examples and the records you score are never stored, whatever these settings; see What's stored. The Data Processing Addendum describes retention in full.