---
title: "Look up player profile"
---

> 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 player profile

Path: Cardzone B2B API › Orders

`POST /api/b2b/v1/player_profiles`

Requires an active API credential with the `orders:create` permission.

Resolves the in-game name and avatar for a top-up recipient so your customer can confirm the account before ordering. Send the same `product_id` and `recipient` you will send to `POST /api/b2b/v1/orders`; missing or unconfigured recipient keys return the same 422 `validation_failed` details. Products with `player_lookup: true` in the catalog support lookups; any other top-up answers `unsupported`.

Available to stores with an enabled postpaid wallet, or a prepaid wallet balance (as returned by `GET /api/b2b/v1/balance`) of at least 100 SAR. Other stores receive `403 player_lookup_requirements_not_met` with the minimum in `error.details`.

The answer is information only: a lookup status never blocks creating the order. Answers are reused for 10 minutes and some games take several seconds to answer. Each store may make 500 lookups per minute across all its API keys (`429 rate_limited` above that); when too many lookups are already waiting on game sites, players without a recent answer get `unavailable`.

Sandbox keys skip the wallet requirement. They validate the recipient of sandbox top-up products, then answer `found` with a static `Sandbox Player` profile.

## Authentication

- `BearerAuth`, http, header `Authorization`

## Request body

_Required._

- `product_id` (`lookupPlayerProfile.product_id`; string, required) — Top-up product id from the products endpoint, the same value you send when creating the order.
  - format `uuid`
- `recipient` (`lookupPlayerProfile.recipient`; object, required) — The complete recipient you will send when creating the order, using the keys in the product's recipient_fields.
  - `name` (`lookupPlayerProfile.recipient.name`; string, optional)
    - example `"Customer Name"`
  - `email` (`lookupPlayerProfile.recipient.email`; string, optional)
    - format `email`
  - `mobile` (`lookupPlayerProfile.recipient.mobile`; string, optional)
    - example `"+966500000000"`
  - `player_id` (`lookupPlayerProfile.recipient.player_id`; string, optional)
    - example `"123456789"`
  - `zone_id` (`lookupPlayerProfile.recipient.zone_id`; string, optional)
    - example `"1234"`
  - `server_id` (`lookupPlayerProfile.recipient.server_id`; string, optional)
    - example `"5678"`
  - `region_id` (`lookupPlayerProfile.recipient.region_id`; string, optional)
    - example `"eu"`
  - `account_tag` (`lookupPlayerProfile.recipient.account_tag`; string, optional)
    - example `"main"`

## Example requests

### PUBG

```json
{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
  "recipient": {
    "player_id": "00123456789"
  }
}
```

### Mobile Legends

```json
{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa2",
  "recipient": {
    "player_id": "12345678",
    "zone_id": "1234"
  }
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://cardzone.ai/api/b2b/v1/player_profiles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
  "recipient": {
    "player_id": "00123456789"
  }
}
'
```

### TypeScript

```typescript
const url = 'https://cardzone.ai/api/b2b/v1/player_profiles';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    product_id: '018f7b75-0194-726a-9814-e26efa39dfa1',
    recipient: {player_id: '00123456789'}
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://cardzone.ai/api/b2b/v1/player_profiles"

payload = {
    "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
    "recipient": { "player_id": "00123456789" }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Lookup answer

#### Example

```json
{
  "status": "found",
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
  "product_code": "pubg-60-uc",
  "recipient": {
    "player_id": "00123456789"
  },
  "profile": {
    "display_name": "PlayerOne",
    "username": null,
    "image_url": null
  }
}
```

- `status` (`lookupPlayerProfile.response.200.status`; string, required) — `found`: show `profile` next to the entered ID and let the customer confirm it. `not_found`: the game reported that the ID does not exist, or it is malformed for the game. Ask the customer to check it; ordering is still allowed. `unavailable`: the game could not answer right now. Let the customer continue without a profile. `unsupported`: this product has no player lookup.
  - one of `"found"`, `"not_found"`, `"unavailable"`, `"unsupported"`
- `product_id` (`lookupPlayerProfile.response.200.product_id`; string, required)
  - format `uuid`
- `recipient` (`lookupPlayerProfile.response.200.recipient`; map<string>, required) — The recipient that was looked up, after trimming. Send the customer's own input when creating the order; the profile never replaces it.
- `profile` (`lookupPlayerProfile.response.200.profile`; object, required, nullable) — Present only when status is found.
  - `display_name` (`lookupPlayerProfile.response.200.profile.display_name`; string, required, nullable) — In-game name to show the customer.
  - `username` (`lookupPlayerProfile.response.200.profile.username`; string, required, nullable) — Account handle, when the game has one separate from the name.
  - `image_url` (`lookupPlayerProfile.response.200.profile.image_url`; string, required, nullable) — Avatar URL, when the game's source exposes one.
    - format `uri`
- `product_code` (`lookupPlayerProfile.response.200.product_code`; string, optional, nullable)

### 401

Missing, revoked, or unknown API key. A live key also gets this while its store is inactive, or until the store's business verification is approved and its primary user's email is verified.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`lookupPlayerProfile.response.401.error`; object, required)
  - `code` (`lookupPlayerProfile.response.401.error.code`; string, required)
  - `message` (`lookupPlayerProfile.response.401.error.message`; string, required)
  - `details` (`lookupPlayerProfile.response.401.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`lookupPlayerProfile.response.401.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 403

`forbidden` when the API credential lacks permission, or `player_lookup_requirements_not_met` when the store does not meet the wallet requirement.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`lookupPlayerProfile.response.403.error`; object, required)
  - `code` (`lookupPlayerProfile.response.403.error.code`; string, required)
  - `message` (`lookupPlayerProfile.response.403.error.message`; string, required)
  - `details` (`lookupPlayerProfile.response.403.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`lookupPlayerProfile.response.403.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 404

`product_not_found`: the product is unknown or deleted, or Cardzone has no way to fulfill it for this store. `error.product_status` is `out_of_stock` or `unavailable` when the product exists.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`lookupPlayerProfile.response.404.error`; object, required)
  - `code` (`lookupPlayerProfile.response.404.error.code`; string, required)
  - `message` (`lookupPlayerProfile.response.404.error.message`; string, required)
  - `details` (`lookupPlayerProfile.response.404.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`lookupPlayerProfile.response.404.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 422

`validation_failed` with field details, or `delivery_method_not_allowed` when this API credential cannot order the product's delivery type

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`lookupPlayerProfile.response.422.error`; object, required)
  - `code` (`lookupPlayerProfile.response.422.error.code`; string, required)
  - `message` (`lookupPlayerProfile.response.422.error.message`; string, required)
  - `details` (`lookupPlayerProfile.response.422.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`lookupPlayerProfile.response.422.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 429

`rate_limited`: too many lookups for this store

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`lookupPlayerProfile.response.429.error`; object, required)
  - `code` (`lookupPlayerProfile.response.429.error.code`; string, required)
  - `message` (`lookupPlayerProfile.response.429.error.message`; string, required)
  - `details` (`lookupPlayerProfile.response.429.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`lookupPlayerProfile.response.429.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`


Source: https://docs.cardzone.ai/reference/player-profiles/create/index.md