API Integration (Advanced)

Get Personalized API - Technical Docs

Overview

Interactive Swagger

Technical Docs

Migrate From User-Level API

Overview

Interactive Swagger

Technical Docs

Migrate From User-Level API

Overview

Interactive Swagger

Technical Docs

Migrate From User-Level API

Get Personalized returns offers selected and ranked for a user on a wall. Display them in the returned array order. Use Get Progress for event completion and credit status.

Quick start

curl --get 'https://publishers.revenueuniverse.com/api/v1/users/YOUR_USER_ID/personalized' \
  --data-urlencode 'wall=YOUR_WALL_ID' \
  --data-urlencode 'numoffers=25' \
  --data-urlencode 'device=android' \
  --data-urlencode 'ip=USER_IP_ADDRESS'
curl --get 'https://publishers.revenueuniverse.com/api/v1/users/YOUR_USER_ID/personalized' \
  --data-urlencode 'wall=YOUR_WALL_ID' \
  --data-urlencode 'numoffers=25' \
  --data-urlencode 'device=android' \
  --data-urlencode 'ip=USER_IP_ADDRESS'
curl --get 'https://publishers.revenueuniverse.com/api/v1/users/YOUR_USER_ID/personalized' \
  --data-urlencode 'wall=YOUR_WALL_ID' \
  --data-urlencode 'numoffers=25' \
  --data-urlencode 'device=android' \
  --data-urlencode 'ip=USER_IP_ADDRESS'

Use GET over HTTPS and URL-encode the actual user identifier in the path. The legacy URL /hotoffers_v3_api.php remains supported; supply uid as a query parameter there. Both URLs support offer_id. No API key is required or validated by this handler.

Request parameters

Parameter

Type

Required

Meaning

user_id

string

Yes on the REST URL

ASCII user identifier in the path. Keep it consistent with clicks and Get Progress, within 255 characters, and do not use the literal {uid}.

uid

string

Yes on the legacy URL

The same user identifier, supplied as a query parameter.

wall

integer

Yes

Numeric wall ID.

numoffers

integer

Unless offer_id is supplied

Maximum offers requested, from 1 through 500. Defaults to 500 for an offer_id lookup when omitted.

offer_id

integer

No

Positive campaign ID. Selects that offer regardless of its rank, if available and eligible for the user. Otherwise returns 404 OFFER_NOT_FOUND.

device

string

No

desktop, ios or android. Omission selects desktop; it does not detect the user’s platform. mobile is deprecated and rejected.

os_version

number

No

Device OS version used in targeting.

ip

string

No

User IP for geographic evaluation. Defaults to the caller’s IP. Cannot be combined with callback.

sid3

string

No

Session correlation value included in standard generated tracking URLs and available as $sid3$ on the postback. Keep ASCII values within 200 characters before URL encoding. Preview destinations can bypass tracking.

api_version

integer

No

Defaults to 3, the envelope documented here. Values 1 and 2 select the legacy flat-array format. Use 3 for this integration.

version

integer

No

Legacy client option, ignored for the v3 envelope. Do not use it to select the response format.

bid_floor

number

No

Positive reward floor for v3 offers. Echoed in the envelope when applied.

experiment_id

string

No

Optional experiment identifier echoed in the envelope when supplied.

include_sortmetric

boolean

No

Accepted but ignored. It adds neither sortmetric nor conversion_rate; use array order.

include

string

No

Accepted but ignored. Every event already contains sid4.

callback

string

No

Deprecated compatibility parameter; provides no JSONP wrapping. Combining it with ip returns 400.

For server-side requests, pass the user’s IP and actual device. A browser request uses the caller’s IP by default, but still needs an explicit ios or android device value for those platforms.

Response envelope

The Swagger reference contains complete schemas and valid examples for single-event and tiered offers.

Field

Type

Meaning

status

string

success.

publisher_id

integer

Publisher account ID.

wall_id

integer

Requested wall ID.

support_id

integer or digit string

User data identifier for support correlation. New user records return an integer; existing records return a digit string. Treat it as an opaque identifier, not a new request ID.

total

integer

Available matching offers before the requested maximum is applied.

offset

integer

Currently 0. This endpoint does not expose an offset paging parameter.

limit

integer

Effective requested maximum, not the number returned. Equals numoffers, or 500 for a single-offer lookup without numoffers.

experiment_id

string or null

Echoed experiment value, when present.

bid_floor

number or null

Applied positive reward floor, when present.

debug_sort_param

integer

Resolved wall sort configuration.

identifier

integer

Split-test bucket selected for this response. Echo this exact value when recording a wall impression, including 0. The active buckets are configuration-dependent.

banned

boolean

Soft missing-credit-report restriction. Offers can still be returned. Hard bans use HTTP 403 instead.

offers

array

Ranked offers. Preserve this order for display.

Offer fields

Field

Type

Meaning

offer_id

integer

Campaign ID.

offer_name

string

Campaign name.

headline

string

Short headline.

description

string

Offer description.

offer_terms

string

Additional terms. Display these with the event requirements.

offer_type

string

Category label, such as Mobile Apps or Purchase.

offer_category

integer

Internal content category: 0 Undefined, 1 Casino/Gambling, 2 Loyalty Offers, 3 Non Branded Submits, 4 Games, 5 Trial/Purchase, 6 Surveys, 7 Branded, 8 Mobile Non Gaming, 9 Alcohol/Tobacco/Drugs, 10 Other Mature, 11 Social Casinos.

offer_flow

string

Undefined, Mobile App Store or Web Landing Page.

payment_model

string

Undefined, CPC, CPI, CPE, MRCPE or CPI with MR Funnel.

reporting

string

Configured crediting-delay label, including Daily, Weekly and other delays. May be empty.

multiple_leads

string or null

Configured repeat policy, described below. It does not by itself establish user eligibility.

reward_expiration_date

integer or null

Campaign reward deadline in Unix seconds using the click snapshot. Null before a click, when no applicable snapshotted window exists, or when the anchor is unavailable.

reward_window_days

integer or null

User-facing campaign reward-window duration in days. Current configuration before a click; the user's stored window after a click. Null when no applicable window exists.

support_expiration_date

integer or null

Support/report-filing deadline in Unix seconds using the click snapshot. Null before a click or when the anchor is unavailable.

support_window_days

integer

Support/report-filing duration in days. Based on current campaign configuration before a click and the stored campaign credit window after a click. Never null; a network default applies without a reward window.

click_url

string

User-specific URL. Serve it as returned. Some policy decisions can return a preview destination instead of a tracking URL.

attributed_click_time

string or null

Most recent known parent click for this user and offer in the applicable wall or unified publisher scope, in UTC. Null when absent.

mobile_package_id

string or null

Mobile app identifier when available.

creatives

array

Objects containing url, integer width and integer height.

tag

string

Single campaign badge.

tags

array of strings

Free-form tags in canonical spelling, ordered by name. Empty when none are configured.

capping

object

Lead, click and publisher cap snapshots, described below.

events

array

Event requirements and rewards.

total_user_reward

number

Sum of listed event rewards in wall display units. May be fractional.

total_user_reward_was

number or null

Pre-promo reward, combined across events for tiered offers. Present only during a promotion.

hot_offers_order

integer

Legacy compatibility field, currently always 0. It is not the response position.

wall_hidden

boolean

Offer is marked not to display in wall browse sections. It remains in the API response and can be kept in progress views.

epc

number

Historical earnings per click.

estimated_completion_time

integer or null

Typical completion time in minutes, when known.

active_date

integer or null

Campaign go-live time in Unix seconds, when available from statistics.

tiers

boolean or null

Legacy field present as true for tiered offers and omitted for single-event offers.

currency_award_with_tiers

number or null

Legacy combined reward field, present for tiered offers. Use total_user_reward for the sum of the listed event rewards.

The v3 response does not contain user_eligible, in_progress, user_completed, recommended_score, sortmetric or conversion_rate. Use Get Progress for progress states. No payout or total_payout is returned here; publisher payouts are documented by Get Offers.

Event fields

Field

Type

Meaning

event_id

string

Configured RevU event identifier, such as install. Matches $event_id$. May be empty; no base prefix or fallback is generated.

sid4

string

Raw offer/tier identifier used for conversion matching. Matches $sid4$. Independent from event_id; an empty value can be valid.

event_description

string

Requirements for this step.

user_reward

number

Wall-currency reward; may be fractional.

conversion_type

integer

Crediting-timing code: 0 unset, 1 Instant, 2 Daily, 3 2-3 Days, 4 3-5 Days, 5 5-7 Days, 6 Weekly, 7 Bi-Weekly, 8 Monthly, 9 Instant pixel/loop, 10 Hourly, 11 Undisclosed.

reward_expiration_date

integer or null

Event override deadline in Unix seconds. Null before a click or without a separate applicable override; use the offer-level deadline when null.

reward_window_days

integer or null

User-facing duration in days for this event's own override. Null means use the offer-level duration. Current configuration before a click; stored event window after a click when a snapshot exists.

is_sequential

boolean

Whether steps must be completed in order.

event_order

integer or false

One-based position for an ordered event, otherwise false. No separate non_linear field is returned.

is_non_crediting

boolean

Tracking-only event with zero reward. Distinct from a payable event whose reward happens to be zero.

Reward and support windows

Before the user clicks an offer, its offer-level and event-level reward_expiration_date values and its support_expiration_date are null. Display reward_window_days and support_window_days as durations at this stage. Do not construct a deadline from the response time.

After a click, campaign and base-event windows use the stored click-time settings. A click made without a reward window keeps a null campaign reward duration and date even if a window is configured later. Event overrides use their stored snapshot when available. A tier added after the click without a snapshot uses its current override configuration with the existing click-backed anchor.

Dates use the stored reward-window start when available, falling back to the click timestamp. This start can reflect an attributed install event, so it need not equal attributed_click_time. Preserve the returned dates rather than recomputing them from that field. A null event duration or deadline uses the offer-level value. An event can have its own reward window even when the campaign has none.

Reward windows concern completion. Support windows concern filing a missing-credit report and do not extend the reward deadline. Support duration remains available when no reward window is configured. Use the returned duration instead of hardcoding a support-window formula or default.

Before-click and clicked examples

These are field excerpts, not complete responses. IDs are fictional. The clicked example uses a stored anchor of 2026-11-01T12:00:00Z (Unix 1793534400): 27 days gives 1795867200, 34 days gives 1796472000, and a 7-day event override gives 1794139200.

Before the click:

{
  "offer_id": 12345,
  "multiple_leads": "once_per_day",
  "reward_expiration_date": null,
  "reward_window_days": 27,
  "support_expiration_date": null,
  "support_window_days": 34,
  "attributed_click_time": null,
  "events": [
    {"event_id": "install", "sid4": "raw-install", "reward_expiration_date": null, "reward_window_days": null},
    {"event_id": "level_5", "sid4": "raw-level-5", "reward_expiration_date": null, "reward_window_days": 7}
  ]
}
{
  "offer_id": 12345,
  "multiple_leads": "once_per_day",
  "reward_expiration_date": null,
  "reward_window_days": 27,
  "support_expiration_date": null,
  "support_window_days": 34,
  "attributed_click_time": null,
  "events": [
    {"event_id": "install", "sid4": "raw-install", "reward_expiration_date": null, "reward_window_days": null},
    {"event_id": "level_5", "sid4": "raw-level-5", "reward_expiration_date": null, "reward_window_days": 7}
  ]
}
{
  "offer_id": 12345,
  "multiple_leads": "once_per_day",
  "reward_expiration_date": null,
  "reward_window_days": 27,
  "support_expiration_date": null,
  "support_window_days": 34,
  "attributed_click_time": null,
  "events": [
    {"event_id": "install", "sid4": "raw-install", "reward_expiration_date": null, "reward_window_days": null},
    {"event_id": "level_5", "sid4": "raw-level-5", "reward_expiration_date": null, "reward_window_days": 7}
  ]
}

After the click, with the same durations in the stored snapshots:

{
  "offer_id": 12345,
  "multiple_leads": "once_per_day",
  "reward_expiration_date": 1795867200,
  "reward_window_days": 27,
  "support_expiration_date": 1796472000,
  "support_window_days": 34,
  "attributed_click_time": "2026-11-01T12:00:00.000000+00:00",
  "events": [
    {"event_id": "install", "sid4": "raw-install", "reward_expiration_date": null, "reward_window_days": null},
    {"event_id": "level_5", "sid4": "raw-level-5", "reward_expiration_date": 1794139200, "reward_window_days": 7}
  ]
}
{
  "offer_id": 12345,
  "multiple_leads": "once_per_day",
  "reward_expiration_date": 1795867200,
  "reward_window_days": 27,
  "support_expiration_date": 1796472000,
  "support_window_days": 34,
  "attributed_click_time": "2026-11-01T12:00:00.000000+00:00",
  "events": [
    {"event_id": "install", "sid4": "raw-install", "reward_expiration_date": null, "reward_window_days": null},
    {"event_id": "level_5", "sid4": "raw-level-5", "reward_expiration_date": 1794139200, "reward_window_days": 7}
  ]
}
{
  "offer_id": 12345,
  "multiple_leads": "once_per_day",
  "reward_expiration_date": 1795867200,
  "reward_window_days": 27,
  "support_expiration_date": 1796472000,
  "support_window_days": 34,
  "attributed_click_time": "2026-11-01T12:00:00.000000+00:00",
  "events": [
    {"event_id": "install", "sid4": "raw-install", "reward_expiration_date": null, "reward_window_days": null},
    {"event_id": "level_5", "sid4": "raw-level-5", "reward_expiration_date": 1794139200, "reward_window_days": 7}
  ]
}

Repeat policies

multiple_leads

Meaning

not_permitted

Repeats are restricted. This is not a guaranteed lifetime limit; tiered offers can credit each event.

once_per_day

Normally counts conversions on the current calendar date.

unlimited

No frequency-count limit; other eligibility rules still apply.

once_per_two_days

Normally counts today and yesterday, not an exact rolling 48-hour interval.

five_per_day

Normally allows five conversions on the current calendar date.

once_per_seven_days

Normally counts today and the previous six dates; no fixed weekday reset.

multiple_leads is null for a missing or unrecognized setting. Date boundaries use the service's configured time zone; daylight-saving behavior can affect availability. The named policy does not promise an exact elapsed-hour reset.

multiple_leads: "once_per_day" normally allows another completion on a later service calendar date, provided other requirements still hold. It does not guarantee a repeat reward.

Get Personalized does not return repeat_available or completion history. Call Get Progress with the same wall/user identifiers and optional offer_id to inspect the repeat-check result, event timestamps and reward states. A missing offer in Personalized can reflect list limits, targeting or other rules; it does not identify a specific repeat restriction. There is no last-24-hours completion filter in either endpoint.

Capping

The three cap flags have different meanings:

Object

Meaning of enabled: true

When enabled: false

Other fields returned when true

lead_cap

A lead cap is configured. Check the remaining count to determine whether it is reached.

No lead cap. The entire object is {"enabled": false}.

cap_scope: "all_conversions", event_id: null, integer remaining_leads_available, integer current_lead_count, and capping_period.

click_cap

A click cap is configured. Check the remaining count to determine whether it is reached.

No click cap. The entire object is {"enabled": false}.

Integer remaining_clicks_available, integer current_clicks_count, and capping_period: "daily_cst".

publisher_cap

This publisher has reached its cap. Stop showing the offer.

Either no publisher cap or a configured publisher cap with room left. The entire object is {"enabled": false}.

Only cap_scope: "publisher" and capping_period: "daily_cst". No count fields.

Publisher caps never return a remaining count, current count or configured maximum. A configured publisher cap of 45 per day with zero conversions and an offer with no publisher cap both return {"enabled": false}. You cannot distinguish those states or calculate the publisher’s remaining quota from this response. Once a publisher cap is reached, the entire object is {"enabled": true, "cap_scope": "publisher", "capping_period": "daily_cst"}.

Lead caps cover all conversions, so lead_cap.event_id is null. Lead and click counts are integers; remaining counts are clamped to zero. Adding current and remaining counts cannot reliably reconstruct a configured maximum after overdelivery. Lead-cap periods include unlimited, hourly, daily_cst, daily_est, daily_pst, daily_gmt, weekly, monthly and total.

When to stop showing an offer

Stop showing an offer if any one of these conditions is true:

  1. lead_cap.enabled == true and lead_cap.remaining_leads_available <= 0.

  2. click_cap.enabled == true and click_cap.remaining_clicks_available <= 0.

  3. publisher_cap.enabled == true.

Combine the conditions with OR. For an offer returned by the API:

const { lead_cap, click_cap, publisher_cap } = offer.capping;
const capReached =
  (lead_cap.enabled === true && lead_cap.remaining_leads_available <= 0) ||
  (click_cap.enabled === true && click_cap.remaining_clicks_available <= 0) ||
  publisher_cap.enabled === true;
const { lead_cap, click_cap, publisher_cap } = offer.capping;
const capReached =
  (lead_cap.enabled === true && lead_cap.remaining_leads_available <= 0) ||
  (click_cap.enabled === true && click_cap.remaining_clicks_available <= 0) ||
  publisher_cap.enabled === true;
const { lead_cap, click_cap, publisher_cap } = offer.capping;
const capReached =
  (lead_cap.enabled === true && lead_cap.remaining_leads_available <= 0) ||
  (click_cap.enabled === true && click_cap.remaining_clicks_available <= 0) ||
  publisher_cap.enabled === true;

These are capacity checks. A false capReached value does not establish that an individual user is eligible. Capacity can change after a response; a cap snapshot does not reserve capacity.

The field shapes and stop-showing conditions match Get Offers. See the Get Offers cap examples for complete objects and full responses. filter[capped_only] is a Get Offers parameter; Get Personalized does not expose it.

Bans and errors

Hard user or IP restrictions return HTTP 403 with a structured error. A successful response with banned: true instead indicates a soft missing-credit-report restriction; it can still contain offers. Render the appropriate support restriction without treating that flag as a hard offer-access ban.

Validation and general failures use this envelope:

{"status":"failure","message":"Invalid device parameter"}
{"status":"failure","message":"Invalid device parameter"}
{"status":"failure","message":"Invalid device parameter"}

Structured errors use this envelope:

{"status":"error","error":{"code":"OFFER_NOT_FOUND","message":"The requested offer was not found or is not available for this user"}}
{"status":"error","error":{"code":"OFFER_NOT_FOUND","message":"The requested offer was not found or is not available for this user"}}
{"status":"error","error":{"code":"OFFER_NOT_FOUND","message":"The requested offer was not found or is not available for this user"}}

HTTP

Code or format

Meaning

400

status: failure with message

Missing or invalid parameters, including non-ASCII user IDs, invalid offer IDs, invalid device values, or ip combined with callback.

403

INVALID_WALL / INVALID_AFFILIATE

Inactive wall or publisher.

403

USER_BANNED / IP_BANNED

Hard user or security restriction.

404

status: failure with message

Wall not found or no offers available.

404

OFFER_NOT_FOUND

Requested offer is unavailable or ineligible for this user.

500

status: failure with message

Unexpected server failure. Retry and contact support if persistent.

Integration practices

Pass the actual device and user IP, keep the user identifier consistent, display offers in returned order, and exclude wall_hidden entries from browsing. Preserve fractional rewards, nullable fields and independent identifiers. Use Get Progress for per-event progress and include support_id when reporting a user-specific issue.

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.

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.

Get Personalized API - Swagger

Get Personalized API - Swagger

Get Personalized API - Migrate from User-Level Offer API

Share feedback on this documentation

On this page

On this page