Trading Card Scanner API

Why building a card scanner is hard

Recognising "a Charizard" is easy. Recognising which Charizard is the part that matters, because the price depends on it.

• The same art is printed many times. 1st Edition and Unlimited, holo and reverse holo, prerelease stamps, retailer exclusives and reprints share one picture. An image match alone picks one of them and can be wrong by hundreds of dollars.
• Every game prints numbers differently. 087/147, OP03-045, SR14-EN027, DG/EN-S03-E028. A scanner has to know each format and the catalog has to store it the same way.
• A match is only useful with an ID and a price. Recognition services return a name; your app still has to map it to a product it can price, list or store.

How the scan works

1. Send one photo as a file upload, base64 JSON or raw image bytes (JPEG, PNG or WebP, up to 8 MB). Phone photos work as they are.
2. The photo is read like a person would read it: name, collector number or card code, set, edition stamp, foil, language, and the grade on a slab.
3. The read is matched against the catalog by printed number first, then name, set and stamp, so the answer is a real product with a TCGPlayer ID.
4. You get a status and ranked candidates: matched when exactly one printing fits, ambiguous when several do, retake when the photo isn't good enough, not_found or unsupported.

Scan a card in a few lines

The same call from a terminal and from a browser or Node app. include=prices adds the top match's prices at no extra charge.

curl -X POST "https://api.tcgapi.dev/v1/identify?include=prices" \
  -H "X-API-Key: YOUR_KEY" \
  -F "[email protected]"

async function scanCard(file) {
  const form = new FormData();
  form.append("image", file); // a File from <input type="file" accept="image/*" capture>
  const res = await fetch("https://api.tcgapi.dev/v1/identify?include=prices", {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });
  const { data, meta } = await res.json();

  if (data.status === "matched") {
    const card = data.candidates[0];
    return { card_id: card.card_id, name: card.name, set: card.set.name, prices: card.prices };
  }
  if (data.status === "retake") throw new Error(data.message); // e.g. glare over the number
  return { choose: data.candidates }; // ambiguous: let the user pick the printing
}

What comes back

A real response for a photo of Darkrai from Burning Shadows, shortened to the first candidate. card_id works with every other endpoint, and suggested_printing picks the printing the photo shows.

{
  "data": {
    "status": "matched",
    "read": { "game": "pokemon", "name": "Darkrai", "number": "87/147", "finish": "holo", "stamp": null },
    "candidates": [{
      "card_id": 24535,
      "tcgplayer_id": 138577,
      "name": "Darkrai",
      "number": "87/147",
      "set": { "name": "SM - Burning Shadows" },
      "match": { "number": "exact", "name": 1, "edition": true },
      "printings": ["Holofoil", "Reverse Holofoil"],
      "suggested_printing": "Holofoil",
      "prices": [{ "printing": "Holofoil", "market_price": 1.23, "price_change_30d": -10.22 }]
    }]
  },
  "meta": { "charged": "scan", "scans_remaining": 24 }
}

What sets it apart

How accurate is it?

Measured on October 14, 2026 with the endpoint's own code against the live catalog. On 81 real phone photos of Pokemon cards and sealed products taken by a card vendor, the right item was confirmed as matched 88% of the time, was among the candidates every time, and no photo was matched to the wrong item. On catalog photos of cards from every game, the right card was among the candidates 92% of the time; most of the rest were versions that share one printed number.

The full method and per-game results are on the Identify reference. For how this compares with other recognition APIs, see Trading card recognition APIs compared.

What it costs

Packs never expire and are separate from your plan's daily request limit. See pricing.

Card scanner API questions

Key API Endpoints