Look up player profile

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.

POST

https://cardzone.ai/api/b2b/v1/player_profiles

Authorization

BearerAuth
HTTP
required

Request body JSON required

product_id
string
required
Top-up product id from the products endpoint, the same value you send when creating the order.

format: uuid
recipient
object
required
The complete recipient you will send when creating the order, using the keys in the product's recipient_fields.
- name
  optional
  string
- email
  optional
  string
  format: email
- mobile
  optional
  string
- player_id
  optional
  string
- zone_id
  optional
  string
- server_id
  optional
  string
- region_id
  optional
  string
- account_tag
  optional
  string
}

Example requests

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

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

Returns

200

Lookup answer

JSON

status
found
or
not_found
or
unavailable
or
unsupported
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.
product_id
string
required
format: uuid
recipient
map of
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
object
or null
required
Present only when status is found.
- display_name
  string
  or null
  required
  In-game name to show the customer.
- username
  string
  or null
  required
  Account handle, when the game has one separate from the name.
- image_url
  string
  or null
  required
  Avatar URL, when the game's source exposes one.
  
  format: uri
}
product_code
optional
string
or null

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.

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  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.
}

403

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

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  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.
}

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.

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  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.
}

422

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

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  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.
}

429

rate_limited: too many lookups for this store

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  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.
}