Skip to main content

Overview

Prism is AdGem's Offer Personalization API. The /v1/offers endpoint is its GraphQL entry point for retrieving targeted offers — all GraphQL queries are sent as POST requests to this single endpoint.

Endpoint​

POST https://targeted-api.adgem.com/v1/offers

Request​

Headers​

HeaderValueRequiredDescription
AuthorizationBearer <your-jwt-token>YesJWT access token obtained from the Tokens endpoint
Content-Typeapplication/jsonYesRequest body format

Body​

The request body must contain a valid GraphQL query in JSON format:

FieldTypeRequiredDescription
querystringYesThe GraphQL query string
variablesobjectNoVariables referenced in the query

Example Request​

curl -X POST https://targeted-api.adgem.com/v1/offers \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetOffers($playerId: String!) { offers(player_id: $playerId) { id name total_payout_usd creatives { name description } } }",
    "variables": {
      "playerId": "user-123"
    }
  }'

Example Response (200 OK)​

{
  "data": {
    "offers": [
      {
        "id": "123456789",
        "name": "Example Offer",
        "total_payout_usd": 1.50,
        "creatives": {
          "name": "Example Offer Creative",
          "description": "Complete this offer to earn rewards."
        }
      }
    ]
  }
}

Error Responses​

401 Unauthorized​

Returned when the JWT token is missing or invalid.

{
  "message": "Invalid or missing token."
}

403 Forbidden​

Returned when the token is valid but lacks the required scopes.

{
  "message": "Forbidden operation."
}

Player ID​

Both queries take a player_id, and the requirements below apply. Two different things are going on, and it is worth keeping them apart:

  • The 255-character maximum is enforced by Prism. Exceed it and the request is rejected with a validation error.
  • The casing and character rules are platform requirements, not Prism validation. Prism accepts uppercase letters, periods, and spaces on player_id. It does not reject them. They still matter, because the ID has to match the one sent at click time for rewards to attribute to the right player — so treat them as required even though this endpoint will not tell you when you break them.
Setting the Player ID

IMPORTANT: The Player ID is Required

The player_id parameter must be set with a unique identifier for each user in your application. This identifies the player so that virtual currency can be attributed to their account via the postback request. The player ID must remain constant for each unique player to:

  • Prevent players from completing an offer more than once
  • Ensure players receive their rewards correctly

Missing Player ID

Tracking URL clicks that do not contain a player_id value will be redirected to a 404 error page.

Player ID Structure Requirements​

RequirementDetails
CaseLetters must be lowercase
CharactersAlphanumeric characters, hyphens, and underscores only
Max Length255 characters (enforced — see below)
ForbiddenEmojis, special characters, uppercase letters
Keep player IDs at 255 characters or fewer

255 characters is the limit to build against. It is enforced, not advisory: a longer player ID is rejected with a validation error and the request returns no data.

Some endpoints accept up to 500 characters, but 255 is the only length that works everywhere in AdGem. Building to 500 means an ID that succeeds on a tracking click and then fails on offer retrieval or player support, so treat 255 as the contract.

If your internal identifiers can exceed 255 characters — long opaque tokens and concatenated composite keys are the usual culprits — map them to a shorter stable identifier before sending them to AdGem. The value only has to be unique and constant per player; it does not have to be your internal primary key. A hash of your internal ID is a good fit: stable and short. Note that a hash is one-way, so keep a lookup table on your side if you need to map back to the internal ID.

Good Examples:

  • abc-123-efg-456
  • user_12345
  • player-a1b2c3d4

Bad Examples:

  • aBc-123-Efg-456 (contains uppercase)
  • player@123! (contains special characters)
  • user-😀 (contains emoji)

Available Queries​

  • offers — Retrieve all targeted offers for a player
  • links — Retrieve tracking links for a player

See Also​