API Integration (Advanced)

Get Offers API - Technical Docs

# Recommended: pass the key as a header
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://publishers.revenueuniverse.com/getoffers_api.php?wall=YOUR_WALL_ID"

# Also supported: pass the key as a query parameter
curl "https://publishers.revenueuniverse.com/getoffers_api.php?wall=YOUR_WALL_ID&api_key=YOUR_API_KEY"

# Recommended: pass the key as a header
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://publishers.revenueuniverse.com/getoffers_api.php?wall=YOUR_WALL_ID"

# Also supported: pass the key as a query parameter
curl "https://publishers.revenueuniverse.com/getoffers_api.php?wall=YOUR_WALL_ID&api_key=YOUR_API_KEY"

# Recommended: pass the key as a header
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://publishers.revenueuniverse.com/getoffers_api.php?wall=YOUR_WALL_ID"

# Also supported: pass the key as a query parameter
curl "https://publishers.revenueuniverse.com/getoffers_api.php?wall=YOUR_WALL_ID&api_key=YOUR_API_KEY"

Base URL

Method: GET only. HTTPS is required.

Authentication

Every request requires two things: your wall ID and your API key.

Item	Where it goes	Notes
`wall`	Query parameter	Your numeric offer wall ID.
`api_key`	Header or query parameter	Your 20-character account API key.

Your API key can be supplied in whichever way fits your stack:

Header: X-API-Key: YOUR_API_KEY
Header: Authorization: ApiKey YOUR_API_KEY
Header: Authorization: Bearer YOUR_API_KEY
Query parameter: api_key=YOUR_API_KEY

Passing the key as a header is recommended so it stays out of URLs, logs, and browser history.

Finding your key: Log into the Publisher Portal and go to My Account → Account API Key. Keep it secret and never expose it in client-side code or public repositories.

Request parameters

Parameter	Type	Required	Description
`wall`	integer	Yes	Your offer wall ID.
`api_key`	string	Yes	Your account API key (or supply via header).
`limit`	integer	No	Page size after filtering. Range 1–10000. Default 100.
`offset`	integer	No	Starting position in the filtered list. Default 0.
`ip`	string (IPv4)	No	IP used for geo evaluation (country/state). Defaults to the caller's IP.
`filter[tag]`	string	No	Exact match on an offer's `tag`.
`filter[platform]`	string	No	`desktop`, `android`, or `ios`. Returns offers that support that platform.
`filter[country]`	string	No	ISO 3166-1 alpha-2 code (e.g. `US`). Returns offers available in that country.

Filtering: server-side vs. your side

You can filter the catalog two ways:

Server-side: pass any of the filter[...] parameters above and RevU returns only matching offers. This is the most efficient way to narrow by tag, platform, or country.
Your side: some attributes are not available as request filters and should be applied to the returned data.

Pagination

total tells you how many offers match your filters before paging. Walk the full catalog by incrementing offset by limit:

Response

A successful request returns status: "success" and a paginated list of offers.

{
  "status": "success",
  "publisher_id": 2,
  "wall_id": 420,
  "total": 2080,
  "offset": 0,
  "limit": 100,
  "offers": [ /* … offer objects … */ ]
}

{
  "status": "success",
  "publisher_id": 2,
  "wall_id": 420,
  "total": 2080,
  "offset": 0,
  "limit": 100,
  "offers": [ /* … offer objects … */ ]
}

{
  "status": "success",
  "publisher_id": 2,
  "wall_id": 420,
  "total": 2080,
  "offset": 0,
  "limit": 100,
  "offers": [ /* … offer objects … */ ]
}

Field	Type	Description
`status`	string	Always `success` on a 2xx response.
`publisher_id`	integer	Your affiliate (publisher) ID.
`wall_id`	integer	The wall the catalog was returned for.
`total`	integer	Number of offers matching your filters, before the `offset`/`limit` page slice.
`offset`	integer	The offset applied to this page.
`limit`	integer	The page size applied to this page.
`offers`	array	The offers for this page (see below).

The offer object

Each entry in offers[] is a complete offer. Fields are grouped below by purpose.

Identity & content

Field	Type	Description
`offer_id`	integer	Unique offer identifier. Use this to de-duplicate and to locate a specific offer.
`offer_name`	string	Internal/campaign name.
`headline`	string	Short marketing headline.
`description`	string	Longer description of the offer.
`offer_terms`	string	Additional terms and conditions.
`preview_url`	string	Landing-page preview without tracking.
`tag`	string	Optional campaign label ("flair") you can group or filter on.

Offer categorization

Offers carry two independent classifications:

Field	Type	Description
`offer_type`	string	The offer's category label. One of: `Undefined`, `Free`, `Purchase`, `Trial`, `Other`, `Mobile Apps`, `Clicks and Videos`, `Studies`, `Contest`.
`offer_category`	integer	RevU's internal content category. See mapping below.

offer_category mapping

ID	Category	ID	Category
0	Undefined	6	Surveys
1	Casino/Gambling	7	Branded
2	Loyalty Offers	8	Mobile – Non Gaming
3	Non Branded Submits	9	Alcohol/Tobacco/Drugs
4	Games	10	Other Mature
5	Trial/Purchase	11	Social Casinos

Rewards & events

Every offer exposes its reward structure through an events[] array, whether it has one step or several. The offer-level total_user_reward is the sum of every event's user_reward.

Field	Type	Description
`total_user_reward`	integer	Total virtual currency a user can earn across all events, in your wall's currency units. Equals the sum of `events[].user_reward`.
`offer_conversion_window`	integer	Base attribution window in days (individual events may override it).
`events`	array	The reward steps for this offer (see below).

Each event in events[]:

Field	Type	Description
`event_id`	string	Identifier for this event/step. Use it for tier-level postback tracking.
`event_description`	string	What the user must do to complete this step.
`user_reward`	integer	Virtual currency awarded to the user for this step (wall currency units).
`payout`	number	Your payout for this step, in USD.
`conversion_type`	integer	Internal classification of the event's conversion type.
`event_conversion_window`	integer	Attribution window for this event, in days.
`event_order`	integer	`false`
`non_linear`	boolean	`true` when the step can be completed independently of the others.

The click URL

The click_url_base is your tracking link for the offer. Before serving it to a user, append that user's identifier to the sid2= parameter.

Field	Type	Description
`click_url_base`	string	Base tracking URL. Append your user identifier to `sid2=` before use.

Required: set your user's ID on sid2=.

Optional additions:

Parameter	Use
`idfa=`	The user's IDFA (iOS only).
`sid3=`, `sid5=`, `sid6=`	Any URL-safe value up to 255 characters. Whatever you pass here is returned to you on the postback for your own tracking.

sid4 is reserved by RevU for the event identifier and should not be set by you.

// Append the user ID to sid2 (and optionally your own tracking values)
let clickUrl = offer.click_url_base.replace('&sid2=', '&sid2=' + encodeURIComponent(userId));

// Append the user ID to sid2 (and optionally your own tracking values)
let clickUrl = offer.click_url_base.replace('&sid2=', '&sid2=' + encodeURIComponent(userId));

// Append the user ID to sid2 (and optionally your own tracking values)
let clickUrl = offer.click_url_base.replace('&sid2=', '&sid2=' + encodeURIComponent(userId));

Mobile

Field	Type	Description
`mobile_package_id`	string	The app's store identifier when applicable (e.g. an Android package name or iOS App Store ID).

Targeting

Field	Type	Description
`platform`	object	Which platforms the offer supports (see below).
`countries`	array	Allowed ISO 3166-1 alpha-2 country codes. Global offers return the full list of supported countries.
`states`	array	Allowed state/province codes, or `["*"]` when all are allowed.
`user_restricted`	boolean	When `true`, the offer should only be shown to a user after you confirm their eligibility via the Get Personalized API.

platform object

Field	Type	Description
`desktop`	boolean	`true` if the offer runs on desktop.
`android`	object	`{ enabled, os_version_min, os_version_max }`.
`ios`	object	`{ enabled, os_version_min, os_version_max }`.

OS version bounds are null when there is no restriction.

Capping

The capping object tells you, in real time, how much room an offer has left so you can avoid showing exhausted offers.

Field	Type	Description
`capping.lead_cap`	object	Conversion (lead) cap status.
`capping.click_cap`	object	Click cap status.

lead_cap

Field	Type	Description
`enabled`	boolean	Whether a lead cap is active.
`cap_scope`	string	The scope the cap applies to (e.g. `all_conversions`).
`event_id`	string	null
`remaining_leads_available`	integer	Conversions still available in the current period.
`current_lead_count`	integer	Conversions used in the current period.
`capping_period`	string	The cap window. One of `unlimited`, `hourly`, `daily_cst`, `daily_est`, `daily_pst`, `daily_gmt`, `weekly`, `monthly`, `total`.

click_cap: when disabled, the object is simply { "enabled": false }. When enabled it adds remaining_clicks_available, current_clicks_count, and capping_period.

Scheduling (dayparting)

Field	Type	Description
`dayparting.available_start_time`	string	Daily start time (e.g. `00:00:00`).
`dayparting.available_end_time`	string	Daily end time (e.g. `23:59:59`).
`dayparting.weekdays_only`	boolean	`true` if the offer runs on weekdays only.
`dayparting.timezone`	string	Timezone the window is evaluated in (e.g. `America/Chicago`).

Performance & creatives

Field	Type	Description
`conversion_rate`	number	null
`epc`	number	Historical earnings per click, network-wide, over the last 7 days.
`reporting`	string	Expected tracking delay: `Instant`, `Hourly`, or `2-3 Days`.
`creatives`	array	Available images/banners, each with `url`, `width`, and `height`.

Best practices

Cache responses for 2-10 minutes. The catalog is well suited to short-term caching and this keeps your integration fast.
Stay under rate limits. Sustained bursts above ~5 requests per minute may be temporarily throttled. Pull on a schedule and cache.
Paginate. Use limit/offset and stop once offset ≥ total.
Honor caps. Skip offers where the relevant cap has no remaining availability.
Respect user_restricted. Only surface restricted offers after confirming eligibility via the Get Personalized API.
Build the click URL per user. Always set sid2= to the user's ID before serving a link.

Errors

Error responses use status: "failure" with a human-readable message.

HTTP	Example `message`	Meaning
400	`Missing or invalid wall parameter`	A required parameter is missing or invalid.
401	`API key is required`	No API key was supplied.
403	`Invalid API key` / `This API is incompatible with your affiliate account status.`	The key is wrong, or your account cannot use this API.
404	N/A	The wall or affiliate could not be found or is inactive.
405	`Method Not Allowed`	Only `GET` is supported.

Explore all our APIs

Get Offers

One call returns your wall's entire offer catalog: fully monetizable, consistently structured, and ready to render.

Get Progress

Look up offer statuses for a user: in-progress offers, credited rewards, pending credits, and reversals, each with per-step detail.

Get Personalized

A per-user, server-ranked offer list with eligibility, personalization, and ban enforcement already applied.