Developer Integration Guide

Everything a developer needs to integrate GTCR Trust Checks, registration, and transfers into your platform.

Request API Keys View Plans

1Get API Keys

→

2Authenticate

→

3Trust Check

→

4Bulk Check

→

5Register

→

6Transfer

→

7Deregister

→

8Go Live

Back to Business

Step 1

Get Your API Keys

GTCR uses two separate API keys. Request both from the GTCR team at connect@thectca.org. Store them securely (environment variables, secrets manager) — never expose them in client-side code or public repositories.

GTCR_API_KEYRead-only

Trust Check lookups (single + bulk). Used before transactions to verify a card's status.

GTCR_PARTNER_WRITE_KEYRead/Write

Registration, transfer, and deregistration. Used when a sale completes or consent changes.

Security best practice: Use the read-only GTCR_API_KEY for all pre-transaction lookups. Reserve GTCR_PARTNER_WRITE_KEY for your server-side transaction completion flow only. If one key is compromised, the blast radius is limited.

Step 2

Authenticate Every Request

Every API call must include your API key. You can pass it three ways — pick one and use it consistently:

Option A — HTTP Header (recommended)

x-gtcr-api-key: YOUR_API_KEY

Option B — Query Parameter (GET only)

?api_key=YOUR_API_KEY

Option C — Request Body (POST only)

{
  "api_key": "YOUR_API_KEY",
  ...other fields
}

A missing or invalid key returns 401 Unauthorized. All responses are JSON.

Step 3

Trust Check — Single Lookup

Check one card against the GTCR registry before a transaction. This is the core pre-purchase verification call. Use your read-only GTCR_API_KEY.

GET

https://true-safe-card-vault.base44.app/functions/trustCheckApi?cert_number=148087893&grading_company=PSA&api_key=YOUR_API_KEY

Trust Check (Single)

Returns the card's GTCR status, registration level, and any active lost/stolen/dispute reports. No owner identity is ever exposed.

Auth: GTCR_API_KEY (read-only)

Required Parameters

cert_number— Certification number on the slab

Optional Parameters

grading_company— PSA, BGS (Beckett), CGC, SGC, HGA, TAG, AGS, C3G, DGA, Other — filters if multiple slabs share a cert

partner_id— Your platform name (audit label, e.g. "cardshow")

Responses

200Card found — see response shape below

200Card not in registry — found: false, card_status: UNREGISTERED

401Invalid or missing API key

400cert_number is required

Example response (card with an active stolen report):

{
  "cert_number": "148087893",
  "grading_company": "PSA",
  "found": true,
  "card_status": "REPORTED_STOLEN",
  "in_registry": true,
  "registration": {
    "registered": true,
    "verification_level": "registered"
  },
  "reports": {
    "total_count": 1,
    "active_count": 1,
    "has_stolen_report": true,
    "has_lost_report": false,
    "has_dispute_report": false
  },
  "card": {
    "grading_company": "PSA",
    "cert_number": "148087893",
    "card_description": "2023 Mike Trout, Topps Chrome, #150",
    "grade": "PSA 10"
  }
}

Decision logic: If reports.active_count > 0, block or flag the transaction and surface a warning. If registration.registered is true, the card has a GTCR owner record — proceed but show "GTCR Registered" in your UI. If found: false, the card has no GTCR history — this is the normal case for most cards.

Step 4

Trust Check — Bulk Lookup

Check up to 500 cards in one request. Ideal for inventory scans, batch pre-listing checks, or marketplace onboarding. Use your read-only GTCR_API_KEY.

POSThttps://true-safe-card-vault.base44.app/functions/trustCheckBulkApi

Trust Check (Bulk)

Runs all lookups in parallel and returns an array of results with the same shape as the single endpoint.

Auth: GTCR_API_KEY (read-only)

Required Parameters

cert_numbers— Array of cert numbers (max 500). Duplicates are auto-removed.

Optional Parameters

grading_company— Filters all lookups in the batch

partner_id— Your platform name (audit label)

Responses

200{ requested: number, results: Result[] }

400cert_numbers must be a non-empty array (max 500)

401Invalid or missing API key

Example request:

curl -X POST https://true-safe-card-vault.base44.app/functions/trustCheckBulkApi \
  -H "Content-Type: application/json" \
  -H "x-gtcr-api-key: YOUR_API_KEY" \
  -d '{
    "cert_numbers": ["148087893", "148087894", "10"],
    "grading_company": "PSA",
    "partner_id": "cardshow"
  }'

Example response (truncated):

{
  "requested": 3,
  "results": [
    {
      "cert_number": "148087893",
      "found": true,
      "card_status": "REGISTERED",
      "registration": { "registered": true, "verification_level": "registered" },
      "reports": { "active_count": 0, "has_stolen_report": false, ... }
    },
    ...
  ]
}

Step 5

Register a Card (After Sale)

When a sale completes and the seller has consented, register the card on GTCR. This creates a Level 1 registration attributed to the seller. Use your write GTCR_PARTNER_WRITE_KEY.

POSThttps://true-safe-card-vault.base44.app/functions/registerCardApi

Register a Card

Creates a Level 1 ('registered') GTCR registration for the seller's card. If the seller has a GTCR account, it links to them; otherwise it's an unclaimed registration they can claim later.

Auth: GTCR_PARTNER_WRITE_KEY (write)

Required Parameters

cert_number— Cert number on the slab

grading_company— PSA, BGS (Beckett), CGC, CGC, SGC, HGA, TAG, AGS, C3G, DGA, Other

card_description— Player/Character, Year, Set, Card #

seller_email— The card's owner (must be the seller)

seller_consent— Must be boolean true — seller explicitly opted in to GTCR registration

Optional Parameters

grade— e.g. 'PSA 10'

card_image— Slab front photo URL

card_image_2— Slab back photo URL

seller_name— Seller's display name

partner_id— Your platform name (audit label)

consent_timestamp— ISO 8601 timestamp of when the seller consented (defaults to now)

Responses

200{ status: 'registered', registration_id, gtcr_registration_number, verification_level: 'registered', card_id, seller_linked, message }

200{ status: 'already_registered', registration_id, gtcr_registration_number, message } — duplicate, no error

401Invalid or missing API key

403seller_consent is not true — registration requires explicit opt-in

400Missing required field

Consent is mandatory. GTCR returns 403 if seller_consent is not true. You must capture the seller's opt-in in your UI before calling this endpoint, and pass the actual consent_timestamp so GTCR's audit trail reflects the real moment of consent. The assertion trail (consent + timestamp) is stored on GTCR; the evidence trail (the actual toggle click, IP, consent text version) stays on your platform.

Example request:

curl -X POST https://true-safe-card-vault.base44.app/functions/registerCardApi \
  -H "Content-Type: application/json" \
  -H "x-gtcr-api-key: YOUR_PARTNER_WRITE_KEY" \
  -d '{
    "cert_number": "148087893",
    "grading_company": "PSA",
    "card_description": "2023 Mike Trout, Topps Chrome, #150",
    "grade": "PSA 10",
    "seller_email": "seller@example.com",
    "seller_name": "Jane Collector",
    "seller_consent": true,
    "consent_timestamp": "2026-09-25T20:05:00.000Z",
    "partner_id": "cardshow"
  }'

Example response:

{
  "status": "registered",
  "registration_id": "abc123...",
  "gtcr_registration_number": "GTCR-REG-G9B94RIHAV",
  "verification_level": "registered",
  "card_id": "def456...",
  "seller_linked": true,
  "message": "Card registered and linked to the seller's GTCR account."
}

Step 6

Transfer on Sale

When a registered card sells and moves to a new buyer, mark the seller's registration as Transferred. If you provide the buyer's email, GTCR emails them a link to claim the registration on their own GTCR account. Use your write key.

POSThttps://true-safe-card-vault.base44.app/functions/transferOnSaleApi

Transfer on Sale

Marks the seller's active registration 'Transferred' (preserved as private provenance) and emails the buyer a claim link if a buyer email is provided.

Auth: GTCR_PARTNER_WRITE_KEY (write)

Required Parameters

cert_number— Cert number of the card that sold

Optional Parameters

grading_company— Filters if multiple slabs share a cert

buyer_email— If provided, buyer gets an email with a claim link

partner_id— Your platform name (audit label)

Responses

200{ status: 'transferred', registration_id, buyer_notified, claim_url, message }

404{ status: 'no_active_registration' } — card wasn't registered, nothing to transfer

401Invalid or missing API key

This does not create a new registration for the buyer — the buyer must claim it via the email link or register manually. The card's GTCR status moves to TRANSFER_PENDING until the buyer claims.

Example request:

curl -X POST https://true-safe-card-vault.base44.app/functions/transferOnSaleApi \
  -H "Content-Type: application/json" \
  -H "x-gtcr-api-key: YOUR_PARTNER_WRITE_KEY" \
  -d '{
    "cert_number": "148087893",
    "grading_company": "PSA",
    "buyer_email": "buyer@example.com",
    "partner_id": "cardshow"
  }'

Step 7

Remove a Registration (Consent Revocation)

When a seller revokes consent or requests removal, deregister their card. The registration is marked "Removed" (not hard-deleted) so the audit trail is preserved. Use your write key.

POSThttps://true-safe-card-vault.base44.app/functions/removeRegistrationApi

Remove Registration

Removes a seller's active GTCR registration. The seller_email must match the registration's owner — partners cannot remove another seller's registration.

Auth: GTCR_PARTNER_WRITE_KEY (write)

Required Parameters

cert_number— Cert number to deregister

seller_email— Must match the registration's owner email

Optional Parameters

grading_company— Filters if multiple slabs share a cert

partner_id— Your platform name (audit label)

reason— Defaults to 'seller_consent_revoked'. Can be any string (e.g. 'seller_request', 'duplicate')

Responses

200{ status: 'removed', registration_id, card_updated, message }

404{ status: 'not_found' } — no matching active registration (idempotent, safe to retry)

401Invalid or missing API key

400Missing required field

Idempotent: if there's no matching active registration, it returns 404 not_found — safe to retry. Call this promptly when a seller revokes consent, for each of their active GTCR registrations.

Example request:

curl -X POST https://true-safe-card-vault.base44.app/functions/removeRegistrationApi \
  -H "Content-Type: application/json" \
  -H "x-gtcr-api-key: YOUR_PARTNER_WRITE_KEY" \
  -d '{
    "cert_number": "148087893",
    "grading_company": "PSA",
    "seller_email": "seller@example.com",
    "reason": "seller_consent_revoked",
    "partner_id": "cardshow"
  }'

Step 8

Integration Checklist

Recommended implementation sequence:

1Request both API keys from connect@thectca.org.
2Store keys in environment variables — never in client-side code or git.
3Build the Trust Check call into your pre-transaction flow (before a buyer can complete checkout). Use GTCR_API_KEY.
4Surface Trust Check results in your UI: show 'GTCR Registered' for registered cards, block/flag transactions with active stolen/lost reports.
5Build the consent capture UI: a clear opt-in toggle the seller must click before registration. Store the consent evidence (timestamp, IP, consent text) on your side.
6Wire registerCardApi into your transaction-completion flow. Pass seller_consent: true and the real consent_timestamp. Use GTCR_PARTNER_WRITE_KEY.
7Wire transferOnSaleApi into your sale flow when a registered card changes hands. Pass the buyer's email so they get a claim link.
8Wire removeRegistrationApi to your consent-revocation flow. Call it for each of the seller's active GTCR registrations when they opt out.
9Test in the GTCR dashboard (code → functions → test) with sample cert numbers before going live.
10Go live. Monitor 401s (key issues) and 403s (consent issues) in your error logs.

Consent Lifecycle

Event	Call
Sale completes (consented)	registerCardApi
Card resold to buyer	transferOnSaleApi
Seller revokes consent	removeRegistrationApi

Audit Trail on GTCR

• Registration → CARD_ADDED event with consent + timestamp
• Transfer → REGISTRATION_TRANSFERRED event
• Removal → STATUS_CHANGED event with reason
• Every lookup → PARTNER_LOOKUP event
• Match on a stolen card → owner auto-notified via partner_match alert

Need Help?

For API keys, technical questions, or integration support, contact the GTCR team.

connect@thectca.org