---
title: "Request a Missing Card (Commercial Agreement Required)"
method: POST
path: "/v1/cards/card-request"
tags: ["Card Details"]
---

# Request a Missing Card (Commercial Agreement Required)

`POST /v1/cards/card-request`

Ask Card Hedge to add a card that is missing from the catalog.

**Requires a commercial agreement with Card Hedge.** Contact Card Hedge to
obtain your Client ID before using this endpoint.

Submit the missing card's player, set, card number, and image; the request
is queued for our data team to review and add. The `token` field must
contain your Client ID provided by Card Hedge.

**Example curl:**
```bash
curl -X POST "https://api.cardhedger.com/v1/cards/card-request" \
     -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "player": "River",
       "set": "2020 Panini Illusions",
       "card_number": "44",
       "subset": "",
       "image_url": "https://i.ebayimg.com/images/g/LssAAOSwjl9h2Q16/s-l1600.jpg",
       "external_id": "RiverTest1",
       "token": "your-client-id",
       "variant": "Blue"
     }'
```

Returns the request status and ID on success.

## Request body

- CardRequestRequest — Request parameters for card request endpoint.
  - `player` string, required — Player or character name
  - `set` string, required — Card set name (e.g., '2020 Panini Illusions')
  - `card_number` string, required — Card number in set
  - `subset` string, nullable — Card subset (optional)
  - `image_url` string, required — URL to card image
  - `external_id` string, required — Your reference ID for tracking. This ID will be included in the webhook response when the card is added.
  - `token` string, required — Your Client ID provided by Card Hedge. This endpoint requires a commercial agreement — contact Card Hedge to obtain your Client ID.
  - `variant` string, nullable — Card variant (e.g., 'Blue', 'Refractor')

## Response `200`

Successful Response

- CardRequestResponse — Response model for card request endpoint.
  - `status` string, required — Request status ('Success' or 'NOT_RUN')
  - `message` string, required — Status message
  - `id` string, nullable — Card request ID (only on success)

## Other responses

- `422` — Validation Error - likely missing the `token` (Client ID) field. This endpoint requires a commercial agreement with Card Hedge. Contact Card Hedge to obtain your Client ID.

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) · [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardhedger/card-hedge-api/revisions/497390569396/schema)