> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gemrate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GemRate ID

> How GemRate identifies cards — the universal ID.

A **GemRate ID** is GemRate's unique identifier for a card **as cataloged by a single
grading company**. It's the key you use across the API: it's returned by cert and spec
lookups, and it's what `GET /v1/cards/{gemrate_id}/population` takes. A GemRate ID is consistent
once assigned.

## One card, up to four IDs

Each grading company — PSA, Beckett, SGC, CGC — catalogs cards independently, so GemRate
mints a **separate ID per grader**. A single real-world card therefore has up to **four**
GemRate ID values, one for each grader's entry. Each ID means *"this card, graded by this
grader."*

## The universal ID

When GemRate recognizes that several per-grader entries are the **same card**, it
**matches** them together and **promotes one of those IDs** to be the
**universal GemRate ID** — the single identifier that represents the card across every
grader.

A grader-scoped response carries both:

* **`gemrate_id`** — the grader-scoped ID for the entry you looked up.
* **`universal_gemrate_id`** — the promoted, cross-grader ID for the same card.

The universal ID is itself one of the card's per-grader IDs (the promoted one). So for the
promoted grader `gemrate_id` and `universal_gemrate_id` are identical, while the other
graders' `gemrate_id`s differ from it.

### When to use the universal or grader-specific

Whenever possible, you should use the universal gemrate ID. The universal ID will not change for a card definition and it can be used to fetch data for any grader.
If the universal gemrate ID is not returned by a response, that is because we have not matched that card across graders. That gemrate ID is still functional in any endpoint,
and if/when the card is matched that ID will still work.

## Where does a GemRate ID come from?

You obtain a `gemrate_id` by looking a card up. Depending on what you already know, there are a few ways in:

* **Cert lookup** — `GET /v1/certs/{grader}/{cert}`. If you have a grading company's
  cert number, this returns that copy's `gemrate_id` (and the
  `universal_gemrate_id` alongside it). The most direct route when you're holding a slab.
* **Catalog downloads** — `GET /v1/catalogs/{catalog}`. Bulk CSV exports list every card in
  a catalog with its `gemrate_id` per row — use these to map IDs in bulk rather than one
  lookup at a time. Availability is limited — see the
  [catalog download endpoint](/api-reference/catalogs/download-a-catalog) for the catalogs you can
  currently request (`psa` and `pokemon`), each gated by its own approved-key allowlist.
* **The web app** — search on [gemrate.com](https://www.gemrate.com/universal-search) and open a card; the
  `gemrate_id` is the hex segment in the URL, right after `/card/`. For example, in
  `https://www.gemrate.com/card/d74f909463a77b5d16a878900d60e2f93710a17f/2025-cooper-flagg-topps-chrome-refractor-251`
  the ID is `d74f909463a77b5d16a878900d60e2f93710a17f` (the trailing slug is just a
  human-readable label and isn't part of the ID).
* **Spec lookup** — `GET /v1/specs/{grader}/{spec_id}`. If you have a grading company's own
  catalog identifier (PSA spec number, Beckett price-item id, etc.), this resolves it to
  the card and returns its `gemrate_id`.

## Example

A 1986 Fleer Michael Jordan #57 graded by all four companies:

| Grader  | GemRate ID |                         |
| ------- | ---------- | ----------------------- |
| PSA     | `abc123…`  | ← promoted to universal |
| Beckett | `def456…`  |                         |
| SGC     | `ghi789…`  |                         |
| CGC     | `jkl012…`  |                         |

After matching, all four entries report `universal_gemrate_id` = `abc123…`, while each
keeps its own grader-scoped `gemrate_id`.