---
title: "Look up players"
description: "Find a top-up recipient's in-game name and avatar so the customer can confirm the account. A lookup never blocks the order."
---

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

# Look up players

This page shows how to check a player's game account before the customer pays. It works for top-up products only.

Customers sometimes type the wrong player ID. A **player lookup** finds the game account for the ID they typed. Then you can ask *"Is this you? **Sandbox Player**"* before they pay. This prevents most top-ups to the wrong account.

## When lookups work

- A product supports lookups when its catalog row has `"player_lookup": true`.
- For any other top-up, the lookup returns `unsupported`.
- Lookups need the same store wallet requirement as live orders (see [store wallet](https://docs.cardzone.ai/concepts/wallet/)). If your store doesn't meet it, lookups return `403 player_lookup_requirements_not_met`.

## Send the same recipient you will order with

[Look up player profile](https://docs.cardzone.ai/reference/player-profiles/create/) takes the `product_id` and the full `recipient` that you will send to [Create order](https://docs.cardzone.ai/reference/orders/create/). If fields are missing, you get the same `422 validation_failed` details as when you create the order.

## Handle all four statuses

| `status` | Show the customer | Let them order? |
| --- | --- | --- |
| `found` | The `profile.display_name` and avatar next to the ID they typed, with a confirm step. | Yes |
| `not_found` | "We couldn't find this ID. Check it and try again." | Yes, if they still want to |
| `unavailable` | Nothing, or "We couldn't check this ID right now." | Yes |
| `unsupported` | Nothing. | Yes |

> **A lookup never blocks an order**
>
> The lookup result is information only. Games are sometimes slow or wrong, so `not_found` does not prove that an ID is invalid.
>
> - ALWAYS let the customer continue.
> - ALWAYS send the ID the customer typed. NEVER send anything from `profile` instead.

## Limits and timing

- Cardzone reuses answers for **10 minutes**. So repeated lookups of the same player are fast.
- Some games take several seconds to answer. Show a loading spinner, and keep the order button enabled.
- Each store can make **500 lookups per minute**, across all its API keys. Above that, you get `429 rate_limited`.
- When too many lookups are already waiting for game sites, players without a recent answer get `unavailable`.

## Full example

```js
// cardzone() stands for your own function that calls the Cardzone API with your API key.
async function confirmPlayer(productId, recipient) {
  const response = await cardzone("POST", "/player_profiles", { product_id: productId, recipient });

  if (response.status === 422) return { kind: "fix_fields", details: response.body.error.details };
  if (!response.ok) return { kind: "skip" }; // 403, 429, 5xx: never block checkout

  const { status, profile } = response.body;
  if (status === "found") return { kind: "confirm", name: profile.display_name, avatar: profile.image_url };
  if (status === "not_found") return { kind: "warn" };
  return { kind: "skip" }; // unavailable or unsupported
}
```

Sandbox lookups check the recipient against the sandbox top-up products. Then they always return `found` with a fixed **Sandbox Player** profile.

Source: https://docs.cardzone.ai/guides/player-lookups/index.mdx