Skip to main content

Overview

The Offer API is a REST API that returns the offers available to your app so you can display them in your own UI. It returns every available offer (single- and multi-reward) by default, along with goal data and a unique ID per offer, and is designed for server-side polling — not real-time client calls.

Base URL

https://offer-api.adgem.com

All endpoints are served under the current API version path, /v1 — for example, https://offer-api.adgem.com/v1/offers. See Versioning.

When to use the Offer API​

Choose the Offer API when you want to build a custom offer experience with full control over presentation through a straightforward REST integration. If you'd rather query offers over GraphQL, see Prism. For a no-code option, use a pre-built SDK or the Web Offerwall.

How it works​

  1. Authenticate with a bearer access token scoped to your app.
  2. Call GET /v1/offers to retrieve the current offers for your app.
  3. Reward players when offers are completed, via postbacks.

Looking up a single offer​

If you already have an offer id, call GET /v1/offers/{id} to fetch that one offer on demand, for example to render a push notification that references a specific offer. Unlike the list endpoint, the lookup also returns offers that are disabled or deleted, and includes a lifecycle status field (active, disabled, or deleted) so you can tell them apart. Offers that have been archived are no longer retrievable and return a 404.

Polling guidance​

The Offer API is not intended for real-time, per-request client calls. Poll on a schedule and cache the results:

  • Poll about once every 5 minutes to keep offers current.
  • Polling far more frequently than recommended is rate-limited and rejected.
  • Offers can re-enter the feed after being temporarily excluded (for example, after day-capping or a temporary pause), so treat each response as the current full set rather than a one-time snapshot.

Leveraging the schema​

A few fields on the Offer object are easy to miss but worth building around.

Ordering offers with network_epc​

network_epc is the network-wide earnings per click (EPC) a campaign is currently performing at on AdGem. If you're presenting offers in a list, sort from highest to lowest network_epc to surface your best-performing offers first.

Validating rewards with payout​

Include payout in your postback response, and use it — rather than a value you compute yourself — to validate any reward you release. It's the exact decimal amount AdGem pays for that conversion.

Surfacing disclaimer and basic_requirements for native offers​

If you're building a native offer experience, make sure the text in disclaimer and basic_requirements is visible to players before they engage with an offer. AdGem Player Support enforces each offer's attribution window as set by the advertiser, so players should know that window exists up front.

Showing time remaining with attribution_window_days​

attribution_window_days is the number of days after a player clicks an offer during which their activity is still attributed to it. Use it in your UI to show players how many days they have left, counting down from when they clicked — not from the offer's own start date.

What is the offer ID?​

An offer is the intersection of an app and a campaign. The offer id uniquely identifies that app/campaign pairing — if campaign 123 runs in both app 456 and app 789, each pairing gets its own offer ID. Knowing which ID a player originally saw also tells you which version of the offer they interacted with.

An offer's ID changes whenever its contract terms change — AdGem issues a new offer ID rather than altering the existing one. Treat an offer's ID as the version of its terms, and refresh your feed regularly so you're always presenting current offers.

State-specific offer targeting​

Some offers in your API response won't have a geo_targeting.countries object. That means the offer is targeted more precisely than at the country level — typically a state, region, or city — via geo_targeting.states or geo_targeting.cities, and it shouldn't be shown to players outside that area even if you otherwise present offers globally or nationwide.