Static API (Legacy)

AdGem Static API Deprecation

The AdGem Static API will be deprecated in 2025. We recommend Publishers migrate to the AdGem Offer API to retain access to our offers. You can find more information HERE. If you have any questions, please contact your dedicated Publisher Support Advocate.

Why the Static API?

The Static API allows Publishers to pull offers and display them natively on their website or app. This integration type can be used in a variety of UIs and works especially well for “Featured Placement” sections. By default, the Static API does not show multi-reward offers or goal-related information.

The Static API returns all available offers and allows Publishers to control sorting and targeting of offers to their Players. It shows a robust response that included fields that the Offer Wall API does not, such as:

network_epc
payout_usd
start_datetime and end_datetime
Detailed targeting: Country, State, City, Connection_Type, Device

The Static API is not designed to be called in real-time client scenarios.

We recommend you call our API every 5 minutes to ensure your players have access to the most up-to-date offers.

Limitations

Some features of the web-integrated AdGem Offerwall are not currently accessible via the Static API. These include:

The AdGem Reward Status model which allows Players to view their In-Progress and Completed offers

** Please keep this in mind prior to implementation. **

Integration

Integrate Static API In a Few Easy Steps

Security Token Request
Customize Offer Experience
Update Static API Link
Service Response

Requirements

Before you Begin

Must have an active AdGem account
Must have a property to your account
In order for your app to have access to AdGem's offers, you will need to ensure your app is approved in the AdGem system. App setup and approval instructions can be found HERE. Please reach out to your dedicated Publisher Support Advocate with any questions

Step 1 - Security Token Request

To get started with the Static API, you will first need to add your property and request an API Key / Security Token from the AdGem Publisher Dashboard.

Request an API Security Token for your Property:

Locate the property
1. Click the Properties & Apps in the left nav
2. Find the property you would like to integrate the Static API
View Property Information
1. Click Options > Edit > API
Submit a request for a token by completing the Request Token form. When completing the token request, please provide details and intentions of how you want to use the Static API.
Upon approval, you will receive an email with your Secret AdGem API Key

Step 2 - Customize Offer Experience

Although this is not the Offerwall web integration, you are required to setup the Offerwall settings for your app.

Locate the property
1. Click the Properties & Apps in the left nav
2. Find the property you will like to integrate Static API to
View Offerwall Information
1. Click Options > Edit > Offerwall
Update the following required fields in the form.
1. Currency Name Singular - Required
2. Currency Name Plural - Required
3. Currency Multiplier - Update If Applicable
4. Offer Filters - Update If Applicable

Step 3 - Update Static API Link

Use the following Static API URL, replacing the values in UPPERCASE with your AdGem App/Property ID and Security Token values respectively:

https://api.adgem.com/v1/all/campaigns?appid=ADGEM_APP_ID&token=ADGEM_APP_SECURITY_TOKEN

Replace ADGEM_APP_ID with the actual AdGem App ID defined in the AdGem Publisher Dashboard > Properties & Apps
Replace ADGEM_APP_SECURITY_TOKEN with the Security Token value you received in Step 1 - Security Token Request substep 4

Endpoint Structure

All calls to the Static API require, at a minimum, two fields: appid and token.

Parameter	Type	Required	Description
appid	integer	Required	This is your app’s unique AdGem App ID, from in the AdGem Publisher Dashboard > Properties & Apps. This parameter is mandatory for a response.
token	string	Required	This parameter represents the Static API Security Token generated from the AdGem Publisher Dashboard. This value is security-sensitive; do not share this or expose it publicly. This parameter is mandatory for a response.
reward_type	string	Recommended	The default request will retrieve *ONLY* Single Rewarded campaigns. For ONLY Multi-Reward campaigns, set the parameter to `multi`. To see ALL offers, set the parameter to `all`. Example for ALL offers: `&reward_type=all` Example for ONLY multi-reward offers: `&reward_type=multi`
country_codes	string	Optional	Optionally, you can filter the response to contain campaigns only for the country code(s) passed in. Multiple country codes can be given and concatenated with a comma. For example, `country_codes=us,gb,fr,de`
platform	string	Optional	Optionally, you can filter the response to contain campaigns only for a specific platform passed in the call to the API. The API will accept the following platform values: `ios`, `android`, `web`, or `all`. Please note that platform is singular and you cannot concatenate platform values. Example: `platform=ios`
categories	string	Optional	Optionally, you can filter the response to contain only certain types of campaigns. The API will accept the following category values: `app`, `trial`, `survey`, `paid`, `free`, `user_info_request`. Please note that using the categories parameter in the API call will override the app’s Offerwall settings configured in the Publisher Dashboard. Example: `categories=app,survey`
tracking_types	string	Optional	Optionally, you can filter the response to contain only certain tracking types. The API will accept the following category values: `CPI`, `CPE`, `CPA`, `Survey` & `CPC`. Please note that all values are case sensitive. These values can be combined in the call to select multiple tracking types. Example: `tracking_types=CPI,Survey`

Example API Request

https://api.adgem.com/v1/all/campaigns?appid=12345&country_codes=us,gb,fr,jp,ch&categories=app&token=faketoken1234

Best Practices

API Rate Limits & Cache

You can make up to 60 requests per minute, per IP address. Each unique result set is cached for 5 minutes.

Polling the API

We highly recommend that you actively poll the Static API every 5 to 10 minutes to get the latest campaign-level information such as caps and price adjustments.

Leveraging the Schema - Tips

Utilizing the network_epc Field

The network_epc field can be extremely valuable to use as a publisher. This value is the network-wide earnings per click (EPC) that a campaign is actively performing at on AdGem. If for example, you are presenting offers in a list to your users, you could leverage the network_epc field by ordering your offers by highest to lowest EPC values on the list.

Including the payout field in your Postbacks

We highly recommend that you include payout in your postback response so that you can track the accurate decimal amount of revenue earned from the user completing the offer. The payout field should be used to validate ANY release of a user's rewards as this is the official and truest amount AdGem will pay for each transaction.

Using the disclaimer field for Native Offers

We highly recommend that publishers ensure that all information included in the disclaimer field is made visible to users interacting with offers. AdGem Player Support will enforce offer attribution windows as set by our advertisers, making it important that your users are aware of this completion window prior to offer engagement.

Step 4 - Service Response

Handling the Response

The response from the Static API will include an array of all campaigns available for your property. Each campaign will include details and information necessary for you to display the right campaigns to the appropriate users.

Service Response

IMPORTANT: Replacing `playerid`

The campaign tracking url (returned in the campaign response) must be modified to replace the dummy parameter {playerid} with your internal parameter which represents the unique player as used internally in your application. This identifies the player so that virtual currency can later be attributed to their account via the callback request. The player ID has to remain constant (for the unique player in your application) so that players are prevented from completing an offer more than once, and are able to receive their rewards.

NOTE: Missing `playerid`

Please note that tracking url clicks that do not contain a playerid value will be redirected to a 404 error page.

REQUIRED: Player ID Structure

All playerid values that you return should only use lowercase alpha numeric values. A good playerid value may look like: abc-123-efg-456, but should NOT look like: aBc-123-Efg-456.

Tracking URL Difference between Multi-Reward and Single Reward

For multi-reward campaigns, the tracking_url field on the campaign will change from click to offer-interstitial. The use and logic are still the same and will not impact the integration or the player flow.

Example Tracking URL for Single Rewarded Campaigns

"tracking_url": "https://api.adgem.com/v1/click?all=1&appid=12345&cid=107&playerid={playerid}"

Example Tracking URL for Multi-reward Campaigns

"tracking_url": "https://api.adgem.com/offer-interstitial?all=1&appid=12345&cid=107&playerid={playerid}"

Static API Response Endpoint Structure

Field	Type	Example	Description
campaign_id	integer	`161`	A unique identifier for this specific offer.
store_id	string	`1384664077`	Google Play or App Store unique namespace or package name
tracking_type	string	`CPI`	The pricing model of this type of offer (CPI, CPE, CPA, CPC)
currency_name_singular	string	`Coin`	The name of your Offerwall virtual currency as set in the AdGem Dashboard
currency_name_plural	string	`Coins`	The name of your Offerwall virtual currency plural form as set in the AdGem Dashboard
network_epc	string	`7.000`	The EPC for this campaign across the network. If the campaign is new and the network EPC has not been calculated the value will return ‘new’
icon	url	`https://adgem-dashboard-production.s3.us-east-2.amazonaws.com/campaigns/545/campaign-offerwall-creatives/icons/201805242053.png`	URL to the icon creative used for the offer
name	string	`Lords Mobile`	Campaign name
tracking_url	url	`https://api.adgem.com/v1/click?all=1&appid=186&cid=545&playerid={playerid}`	The URL the end-user should be sent to on the click. Important, the {playerid} must be replaced with the unique id for your player on your system. If the campaign is multi-reward, then the link will direct the player to an interstitial page.
instructions	string	`Download and Open the App, Redeem your points!	Information on exactly what a user must do in order to complete the offer and be rewarded. Instruction steps are parse by comma. For example: 1. Download and Open the App 2. Redeem your points!
description	string	`Battle in a world of chaos in Lords Mobile, the latest real-time strategy game from IGG`	Brief copy description of the campaign.
category_1	string	`app`	The offer category type. Possible values include: app, survey, trial, free, paid, user_info_request
category_2	string	`free`	The offer category type. Possible values include: app, survey, trial, free, paid, user_info_request
amount	integer	`25`	The amount of virtual currency awarded to the user for fully completing an offer. This is calculated according to the campaign payout and the exchange rate you have set in the AdGem Publisher Dashboard for your Offerwall. - `Single Rewarded Campaign` displays the potential earnings a user can make for completing the offer - `Multi-Reward Campaign` displays sum of potential earnings the user can earn by summing the total of all goal payouts.
payout_usd	string,5 decimal places	`0.25200`	The amount of USD earned for completing a single offer or completing all goals for multi-reward. - `Single Rewarded Campaign` displays the potential payout for when a user completes an offer - `Multi-Reward Campaign` displays sum of potential payout for when a user completes all goals.
start_datetime	timestamp	`2018-05-24 16:34:45`	The datetime this campaign was set to active status.
end_datetime	timestamp	`2019-01-07 04:59:59`	The datetime this campaign will be set to inactive status.
is_multi_reward	boolean	`true` / `false`	Indication if this offer is Multi-Reward or Single Reward. - `true` means this campaign contains multiple goals for the player to complete. - `false` means this campaign only has one goal/event for the player to complete.
completion_difficulty	integer	`1`	Indicates the level of difficulty in completing an offer. Please reference the Completion Difficulty Scale for more information.
Country, State, City	array	`Country`, `State`, `City` items contain an array with an `include` and `exclude` arrays. The include array contains the information acceptable for the campaign. The exclude array contains information that is not acceptable for the campaign.
Country, State, or City include or exclude `id`	integer	`164`	The geo ID on the AdGem network.
Country, State, or City include or exclude `code`	string	`DE`	The ISO country code.
Country, State, or City include or exclude `name`	string	`Germany`	The full name of the geo.
Connection_Type	array	Indicates the connection type allowed by the campaign.
Connection_Type.cellular	boolean	`true`	Campaign either allows or doesn’t allow traffic from cellular connections.
Connection_Type.wifi	boolean	`true`	Campaign either allows or doesn’t allow traffic from wifi connections.
Device	array	`Device` item contains an array with an `include` and `exclude` arrays. The include array contains the devices that are acceptable for the campaign. The exclude array contains devices that are not acceptable for the campaign.
OS	array	Indicates the operating system for which the campaign is available.
OS.android	boolean	`true/false`	Indicates if Android traffic is allowed for the campaign.
OS.ios	boolean	`true` / `false`	Indicates if iOS traffic is allowed for the campaign.
OS.web	boolean	`true` / `false`	Indicates if Web traffic is allowed for the campaign.
OS.min_ios	string	`10.1`	The minimum iOS version for traffic allowed on this campaign. Default value is null.
OS.max_ios	string	`11`	The maximum iOS version for traffic allowed on this campaign. Default value is null.
OS.min_android	string	`4`	The minimum Android version for traffic allowed on this campaign. Default value is null.
OS.max_android	string	`8.0`	The maximum Android version for traffic allowed on this campaign. Default value is null.

Example of a Successful API Response

  {
      "status": "success",
      "data": {
          "107": {
              "Offer": {
                  "campaign_id": 107,
                  "store_id": "1439500962",
                  "tracking_type": "CPI",
                  "currency_name_singular": "Coin",
                  "currency_name_plural": "Coins",
                  "network_epc": "new",
                  "icon": "https://adgem-dashboard-production.s3.us-east-2.amazonaws.com/campaigns/107/campaign-offerwall-creatives/icons/9vBzpAGqNG50g4cyrdIdvcW2WY23DfC6Hej8bxln.jpeg",
                  "name": "Idle Jackpot",
                  "tracking_url": "https://api.adgem.com/v1/click?all=1&appid=12345&cid=107&playerid={playerid}",
                  "instructions": "Download and Open the App,Redeem your points! *New Users Only",
                  "description": "Grow your jackpot! Earn money while you sleep! Wake up and collect! Compete against your friends ",
                  "category_1": "app",
                  "category_2": null,
                  "amount": 300,
                  "payout_usd": "3.00000",
                  "start_datetime": "2018-05-03 00:00:00",
                  "end_datetime": "2022-12-22 04:59:59",
                  "is_multi_reward": "false",
                  "completion_difficulty": 1
              },
              "Country": {
                  "include": {
                      "US": {
                          "id": 243,
                          "code": "US",
                          "name": "United States"
                      }
                  },
                  "exclude": []
              },
              "State": {
                  "include": [],
                  "exclude": []
              },
              "City": {
                  "include": [],
                  "exclude": []
              },
              "Connection_Type": {
                  "cellular": true,
                  "wifi": true
              },
              "Device": {
                  "include": [],
                  "exclude": []
              },
              "OS": {
                  "android": false,
                  "ios": true,
                  "web": false,
                  "min_ios": null,
                  "max_ios": null,
                  "min_android": null,
                  "max_android": null
              }
          },
      ...
      }
  }

Available `tracking_url` Parameters:

Parameter	Description
gaid	Google Advertising ID, available when the developer is using Google Play Services. This is a required field if you’re displaying the offer(s) in-app and have access to this advertising ID.
idfa	Apple Advertising ID, available when the user has not limited ad tracking. This is a required field if you’re displaying the offer(s) in-app and have access to this advertising ID.
app_version	The version of your app where the click originated
device	The user’s device type, for example ‘Moto E Plus’
device_name	The user’s device name
ip	The IP Address for the user who completed the offer
useragent	The User Agent from the user’s default browser app
os_version	The user’s Operating System version number
platform	The platform this user’s device is using, for example ‘ios’
player_age	The user’s age as set by the publisher
player_gender	The user’s gender as set by the publisher
player_payer	A boolean value, as set by the publisher
player_iap_total_usd	A integer value, as set by the publisher
player_created_at	A datetime stamp without the time zone, as set by the publisher
player_level	The level achieved by a player as set by the publisher
placement	A integer value that represents the placement of the ad unit as set by the publisher
c1	A custom parameter value as set by the publisher
c2	A custom parameter value as set by the publisher
c3	A custom parameter value as set by the publisher
c4	A custom parameter value as set by the publisher
c5	A custom parameter value as set by the publisher

Call Examples

PHPPythonRuby

<?php
// Initialize cURL and make the request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.adgem.com/v1/all/campaigns?appid=ADGEM_APP_ID&token=ADGEM_API_TOKEN');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// Decode the response into a PHP associative array
$response = json_decode($response, true);

// Make sure that there was not a problem decoding the response
if(json_last_error()!==JSON_ERROR_NONE){
  throw new RuntimeException(
      'API response not well-formed (json error code: '.json_last_error().')'
  );
}

// Print out the response details or any error messages
if(isset($response['status']) && $response['status']==="success"){
  echo 'API call successful';
  echo PHP_EOL;
  echo 'Response Data: <pre>'.print_r($response['data'], true).'';
  echo PHP_EOL;
}else if(isset($response['status']) && $response['status']==="error"){
  echo 'API call error';
  echo PHP_EOL;
  echo 'Errors: <pre>'.print_r($response['data'], true).'';
  echo PHP_EOL;
}else{
  echo 'API call failed';
  echo PHP_EOL;
  echo 'Errors: <pre>'.print_r($response['data'], true).'';
  echo PHP_EOL;
}
?>

  # importing the requests library
  import requests

  # defining the api-endpoint
  API_ENDPOINT = "https://api.adgem.com/v1/all/campaigns?appid=ADGEM_APP_ID&token=ADGEM_API_TOKEN"

  # your Adgem App ID and API Token
  ADGEM_APP_ID = "xxxxx"
  ADGEM_API_TOKEN = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

  # data to be sent to api
  data = {'appid': ADGEM_APP_ID,
          'token': ADGEM_API_TOKEN}

  # sending post request and saving response as response object
  r = requests.post(url = API_ENDPOINT, data = data)

  # extracting response data
  response_data = r.data
  print(response_data)

  require 'net/http'
  require 'json'

  url = 'https://api.adgem.com/v1/all/campaigns?appid=ADGEM_APP_ID&token=ADGEM_API_TOKEN'
  uri = URI(url)
  response = Net::HTTP.get(uri)
  JSON.parse(response)