Offer API
The Offer API is AdGem's REST API for retrieving the raw offer catalog and building your own UI on top of it. You control everything: the ranking, the filtering, and the presentation.
Why the Offer API
The Offer API returns the full set of available offers with rich metadata, and leaves the logic to you. Nothing is pre-ranked or personalized — you decide how offers are ordered and shown. That's the most work of any integration, and the most control.
When to choose it
- You need total control over ranking and presentation.
- You have your own ranking or personalization system you want to feed with raw catalog data.
- You have a hard requirement for raw data access (for example, data-residency or compliance needs).
If you want a custom UI but would rather build on AdGem's personalization than your own ranking, Prism is the recommended option. If you don't need to build a UI, see Pre-built.
Attribution
Each offer's links.click_url is returned ready to fire. Because you own the click, you're responsible for decorating it with the device advertising ID so installs can be attributed deterministically.
We always recommend collecting IDFA and GAID from your users in compliance with Apple's App Tracking Transparency (ATT) requirements, and where your app has a user's advertising ID, sending it to AdGem is required. See Mobile Advertising IDs for our full recommendation, including why we don't recommend gating Arcade or rewarded-offer access behind ATT opt-in.
Read the advertising ID in your app — IDFA on iOS (after obtaining App Tracking Transparency consent) or GAID on Android — and append it to the click_url before opening it.
On iOS:
<click_url>&idfa=<IDFA>
On Android:
<click_url>&gaid=<GAID>
AdGem passes the ID to the advertiser's measurement partner (Adjust, AppsFlyer, etc.) on the click, provided the advertiser's tracking template includes the corresponding macro. The measurement partner then matches the install to the click by device ID. When the user has allowed tracking in both your app and the advertised app, this is the most reliable attribution there is; without it, matching falls back to fingerprint matching and, on iOS, SKAdNetwork — far less reliable.
The advertising ID can only be read by native app code — a browser or WebView cannot supply it. Read it natively and append it to the click_url before firing the click.
Click URL parameters
Replace {playerid} in links.click_url with your player's ID and the URL is ready to fire. Keep the rest of the URL exactly as returned, and append any additional parameters to the end.
| Parameter | Description |
|---|---|
idfa / gaid | The device advertising ID. Required wherever your app has it. See Attribution. |
c1 to c5 | Custom values you want returned on the postback, such as a session ID or a sub-publisher ID. c1 to c4 accept up to 99 characters; c5 accepts up to 200. Each comes back as the matching {c1} to {c5} postback macro. |
platform | The platform of the user's device (for example, ios). |
os_version | The user's operating system version. |
app_version | The version of your app where the click originated. |
device | The user's device type (for example, Moto E Plus). |
Parameter names and values are case-sensitive. If an optional value fails validation, AdGem drops that value and still records the click.
<click_url>&idfa=<IDFA>&c1=<session_id>&c2=<sub_publisher_id>
Build with the Offer API
See the Offer API reference for the endpoint, authentication, pagination, and examples.