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).

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.

Rewards & events

Field	Type	Description
`total_user_reward`	number	Total virtual currency the user can earn across all events (sum of `events[].user_reward`).
`total_payout`	number	Your total payout for the offer in USD (sum of `events[].payout`).
`offer_conversion_window`	integer	Base attribution window in days (events may override).
`events`	array	The reward steps (see below).

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.
`payout`	number	Your payout for this step (USD).
`conversion_type`	integer	Internal classification of the conversion.
`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.

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`.

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}`	—	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.

Share feedback on this documentation

Get Personalized API - Swagger

Get Personalized API - Migrate from User-Level Offer API