API Integration (Advanced)

Get Personalized API - Technical Docs

curl "https://publishers.revenueuniverse.com/api/v1/users/USER_ID/personalized?wall=YOUR_WALL_ID&numoffers=25&device=ios"

curl "https://publishers.revenueuniverse.com/api/v1/users/USER_ID/personalized?wall=YOUR_WALL_ID&numoffers=25&device=ios"

curl "https://publishers.revenueuniverse.com/api/v1/users/USER_ID/personalized?wall=YOUR_WALL_ID&numoffers=25&device=ios"

Endpoint

Method: GET. HTTPS is required.

Authentication

This endpoint is scoped to your wall and the user you request. No API key is required. You identify the request with two values:

Item	Where it goes	Notes
`uid`	Path	The user identifier from your integration.
`wall`	Query parameter	Your numeric offer wall ID.

Request parameters

Parameter	In	Type	Required	Description
`uid`	path	string	Yes	The user's identifier in your integration (ASCII).
`wall`	query	integer	Yes	Your offer wall ID.
`numoffers`	query	integer	Yes	How many top-ranked offers to return (1–500).
`sid3`	query	string	No	Your session/correlation token. It is embedded into the returned `click_url` and returned to you on the postback.
`device`	query	string	No	`desktop`, `ios`, or `android`. Auto-detected on client-side calls; pass it explicitly server-side. (`mobile` is not accepted.)
`ip`	query	string (IPv4)	No	Client IP for geo evaluation. Defaults to the caller's IP; set it when calling server-side.
`os_version`	query	number	No	The requesting device's OS version (e.g. `17.1`).
`include_sortmetric`	query	boolean	No	When true, include `sortmetric` and `conversion_rate` on each offer.
`bid_floor`	query	number	No	Exclude offers whose reward value is below this floor.
`experiment_id`	query	string	No	An experiment identifier echoed back in the response.

numoffers controls how many offers you receive, returned in ranked order (best first). Each offer's position is also given explicitly as hot_offers_order. The response reports total (the number of eligible offers for the user before the numoffers cut) so you can tell how deep the user's eligible pool is. This endpoint returns the top N; it is not a paged feed (offset is always 0).

The response

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

{
  "status": "success",
  "publisher_id": 45,
  "wall_id": 123,
  "support_id": 567890,
  "total": 120,
  "offset": 0,
  "limit": 25,
  "experiment_id": "exp_hot_2026_04",
  "bid_floor": 1.5,
  "offers": [ /* … ranked offer objects … */ ]
}

{
  "status": "success",
  "publisher_id": 45,
  "wall_id": 123,
  "support_id": 567890,
  "total": 120,
  "offset": 0,
  "limit": 25,
  "experiment_id": "exp_hot_2026_04",
  "bid_floor": 1.5,
  "offers": [ /* … ranked offer objects … */ ]
}

{
  "status": "success",
  "publisher_id": 45,
  "wall_id": 123,
  "support_id": 567890,
  "total": 120,
  "offset": 0,
  "limit": 25,
  "experiment_id": "exp_hot_2026_04",
  "bid_floor": 1.5,
  "offers": [ /* … ranked offer objects … */ ]
}

Field	Type	Description
`status`	string	`success` on a 2xx response.
`publisher_id`	integer	Your affiliate (publisher) ID.
`wall_id`	integer	The wall the request was for.
`support_id`	integer	A reference ID for this request, useful when contacting support.
`total`	integer	Eligible offers for the user before the `numoffers` cut.
`offset`	integer	Always `0` (this endpoint returns the top N, not pages).
`limit`	integer	The number of offers returned (equals `numoffers`).
`experiment_id`	string	null
`bid_floor`	number	null
`offers`	array	The ranked offers (see below).
`identifier`	integer	Split-test bucket that ranked this response. `0` means no bucket was assigned (split testing disabled or the wall pinned to a fixed value).
`debug_sort_param`	integer	Resolved `WALL_SORT_*` constant used to rank this response.

The offer object

Each entry in offers[] describes one offer. The content, categorization, and reward fields match the Get Offers API; the remaining fields add per-user context.

Identity & content

Field	Type	Description
`offer_id`	integer	Unique offer identifier.
`offer_name`	string	Internal/campaign name.
`headline`	string	Short marketing headline.
`description`	string	Longer description. Display this to the user.
`offer_terms`	string	Terms and requirements. Display this to the user.
`tag`	string	Optional campaign label.

Categorization

Field	Type	Description
`offer_type`	string	Category label: `Undefined`, `Free`, `Purchase`, `Trial`, `Other`, `Mobile Apps`, `Clicks and Videos`, `Studies`, `Contest`.
`offer_category`	integer	Internal content category (0–11): 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	Offer flow classification: `Undefined`, `Mobile App Store`, or `Web Landing Page`.
payment_model	string	Publisher payment model: `Undefined`, `CPC`, `CPI`, `CPE`, `MRCPE`, or `CPI with MR Funnel`.

Rewards & events

Field	Type	Description
`total_user_reward`	number	Total virtual currency the user can earn across all events (sum of `events[].user_reward`).
`reward_expiration_date`	integer	Unix timestamp (seconds) when the campaign-level reward window expires.
`events`	array	The reward steps (see below).
`total_user_reward_was`	number	Pre-promo counterpart of `total_user_reward` (combined across tiers for tiered offers).
`tiers`	boolean	Whether the offer is tiered.
`currency_award_with_tiers`	number	Combined currency award across tiers.

Each event in events[]:

Field	Type	Description
`event_id`	string	Identifier for this step, used for tier-level postback tracking. The base step is `base_<offer_id>`.
`event_description`	string	What the user must do for this step.
`user_reward`	number	Virtual currency awarded to the user for this step.
`conversion_type`	integer	Internal classification of the conversion.
`reward_expiration_date`	integer	Unix timestamp (seconds) when this event's reward window expires; `null` when it inherits the campaign-level window.
`event_order`	integer	`false`
`is_sequential`	boolean	`true` when the tier must be completed in order.
is_non_crediting	boolean	`true` when this event is a non-crediting tracking event: it fires a postback but awards no currency (`user_reward` is 0) and is never credited to users.
sid4	string	Legacy per-event identifier: the raw advertiser-side value conversions are matched on. Matches the $sid4$ postback macro.

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.
`capping.publisher_cap`	object	Publisher-level cap status. Only `{ "enabled": false }` when not at cap.

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.

The click URL

Field	Type	Description
`click_url`	string	A complete, user-specific tracking URL. Serve it as-is. Do not edit it. If you passed `sid3`, it is already embedded here and will return on your postback.

Unlike the Get Offers API (which gives a click_url_base template you complete per user), this URL is already personalized for the user you requested.

Per-user status

These fields reflect the requested user's relationship to the offer and are returned when available.

Field	Type	Description
`user_eligible`	boolean	Whether the user is eligible for the offer.
`in_progress`	boolean	Whether the user has started the offer.
`user_completed`	boolean	Whether the user has completed the offer.
`recommended_score`	number	The personalization score used in ranking.
`hot_offers_order`	integer	The offer's rank in this response (lower is higher-ranked).
`attributed_click_time`	string	null

When you request include_sortmetric=true, each offer may also include sortmetric and conversion_rate.

Mobile, performance & creatives

Field	Type	Description
`mobile_package_id`	string	null
`epc`	number	Historical earnings per click (network-wide, last 7 days).
`reporting`	string	Expected tracking delay: `Instant`, `Hourly`, or `2-3 Days`.
`creatives`	array	Images, each with `url`, `width`, and `height`.
`active_date`	integer	Campaign go-live time as Unix epoch seconds.
`estimated_completion_time`	integer	Minutes a typical user takes to complete this offer. Null when unknown.

Handling banned or ineligible users

If the user (or their IP) is banned, the endpoint returns HTTP 403 with a structured error you can branch on:

{
  "status": "error",
  "error": { "code": "USER_BANNED", "message": "User is banned from accessing offers" }
}

{
  "status": "error",
  "error": { "code": "USER_BANNED", "message": "User is banned from accessing offers" }
}

{
  "status": "error",
  "error": { "code": "USER_BANNED", "message": "User is banned from accessing offers" }
}

error.code is USER_BANNED or IP_BANNED. This makes the endpoint a convenient ban check for support workflows: a 403 with one of these codes is a definitive "do not serve."

Best practices

Call on demand, don't store. Results are user- and moment-specific; fetch them when you're about to render, rather than caching per user.
Prefer client-side calls so device and IP are auto-detected; if you must call server-side, pass device and ip that match the real client.
Serve click_url unmodified. It is already personalized for the user.
Use the per-user status (in_progress, user_completed) to tailor the UI. For example, surfacing progress or hiding finished offers.
Handle 403 bans explicitly using error.code.
Display description and offer_terms so users understand what's required to earn the reward.

Errors

HTTP	Shape	Example	Meaning
400	`{status: "failure", message}`	`Invalid Number of Offers (min is 1, max is 500)`	Missing or invalid parameter (e.g. `Invalid Wall ID`, `Missing UID`, `Invalid device parameter`).
403	`{status: "error", error: {code, message}}`	`USER_BANNED` / `IP_BANNED`	The user or IP is banned.
404	`{status: "failure", message}`	`Wall not found` / `No offers available`	Resource not found or nothing eligible.
500	`{status: "failure", message}`	N/A	Unexpected server error.

Support

For technical questions, contact your account manager or sales contact. Include the support_id from the response when reporting an 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 - Migrate from User-Level Offer API

Share feedback on this documentation

On this page

Subtle light blue dot pattern on a white background.

Get Personalized API - Technical Docs

Quick start

Authentication

Request parameters

Ranking and how many you get

The response

The offer object

Identity & content

Categorization

Rewards & events

Capping

The click URL

Per-user status

Mobile, performance & creatives

Handling banned or ineligible users

Best practices

Errors

Support

Explore all our APIs

Get Offers

Get Progress

Get Personalized

Explore all our APIs

Get Offers

Get Progress

Get Personalized