Accuracy & methodology
Identification that refuses to be confidently wrong.
This is the operating principle behind every response CardVault Identify returns. Here's exactly how the confidence score and needsReview flag work, with real examples — not a marketing number.
What the confidence score actually is
Every identify result carries a confidence value between 0 and 1. It isn't a raw similarity score from a nearest-neighbor lookup — it's calibrated to an estimate of P(correct): the probability the returned card is the right one, given everything we corroborated about the image.
A visual fingerprint match against our own index is one input. So is agreement (or disagreement) from a second adjudication pass. When those signals line up, confidence is high and card is populated. When they don't, confidence drops — and below a floor, we don't guess.
You can layer your own floor on top of ours. If your product needs a stricter bar than our default — say, for anything that touches a price or a grading submission — treat any confidence under your own threshold the same way you'd treat needsReview.
Why we don't publish one accuracy percentage
A single accuracy number is easy to print and easy to game — it doesn't say whether the misses were caught or shipped as confident wrong answers. We haven't run a public, independently reproducible benchmark across every game and sport in our catalog, so we're not going to publish a number we can't stand behind.
The number that actually matters is our catastrophic-error rate — how often we hand back the wrong card with high confidence. We drive that toward zero by design: when we can't corroborate a match, we say so instead of guessing. A wrong-but-confident answer costs your users trust; an honest needsReview costs a follow-up screen.
That's the trade we've made on purpose. If a competitor's page shows you an accuracy percentage, ask what happens to the misses that percentage doesn't count.
Two real responses, side by side
The same endpoint, the same response shape, two different outcomes. Both are HTTP 200 — needsReview is not an error.
A confident hit
curl -X POST https://aicardvault.io/api/v1/identify \
-H "Authorization: Bearer $YOUR_API_KEY" \
-F front=@card.jpg \
-F category=pokemon{
"ok": true,
"result": {
"card": {
"name": "Charizard ex",
"set": "Obsidian Flames",
"number": "125/197",
"year": "2023",
"rarity": "Double Rare",
"language": "en"
},
"confidence": 0.94,
"needsReview": false,
"reviewReason": null,
"alternates": []
}
}confidence is comfortably above our floor and card is fully populated — safe to display directly.
An honest needsReview miss
curl -X POST https://aicardvault.io/api/v1/identify \
-H "Authorization: Bearer $YOUR_API_KEY" \
-F front=@worn_card.jpg \
-F category=sports{
"ok": true,
"result": {
"card": null,
"confidence": 0.41,
"needsReview": true,
"reviewReason": "confidence_below_floor",
"alternates": [
{ "name": "1989 Score #1", "set": "Score", "confidence": 0.41 },
{ "name": "1989 Score #1B", "set": "Score", "confidence": 0.33 }
]
}
}card is null and needsReview is true — but it's still a 200. alternates gives you a ranked list for an "is this your card?" picker instead of a silent wrong answer.
Why this matters, by use case
A confidently wrong ID costs something different depending on what you're building on top of it.
Where needsReview fires more often — by design
Coverage isn't uniform across every game and sport we support, and we'd rather tell you that than smooth it over. Newer or fast-growing sets — One Piece, Lorcana — are earlier in ingest, so needsReview fires more often there than on a deeply indexed game like Pokémon or Magic.
Sports is led by football's index; other sports lean more on vendor recognition than our own catalog, so the same honest-miss behavior applies more frequently there too.
As the catalog and the correction flywheel grow, these gaps close — but we're not going to claim uniform coverage today when it isn't there yet. See the live per-game counts on the card database.
Accuracy FAQ
The two questions we get most about accuracy, pulled straight from the docs FAQ.
How accurate is it, really?
For indexed TCG games, matches are driven by a visual fingerprint against our own catalog and are calibrated to real P(correct). But the number that matters is our catastrophic-error rate — how often we return the wrong card confidently — and we drive that toward zero by refusing to answer when we can't corroborate. When confidence is below our floor or our adjudicator dissents, you get needsReview:true instead of a wrong ID.
What does needsReview mean, and how should I handle it?
needsReview:true with card:null means we couldn't confidently identify the card. It's still an HTTP 200. Best guesses appear in the alternates array with per-candidate confidence, ideal for a 'Is this your card?' picker. Treat it as 'ask the user to confirm,' not as an error.
See it live on your own card
The same confidence score and needsReview behavior described here is exactly what the free scanner returns.