Rewarded Offers API

Version 1.3 — added performance_d0, performance_d7, performance_d30 fields to offer objects. See the changelog for details.

The Rewarded Offers API enables you, as an authorised publisher, to programmatically fetch available and active rewarded offers — including mobile games and other app categories — and render them inside your own application or website. Unlike the IFrame Integration, the API gives you full control over the presentation layer while Prime Earn handles offer sourcing, reward logic, and attribution.

Who is this guide for? This document is intended for developers at partner publisher companies who wish to build a custom UI on top of our offer inventory. If you are looking for the no-code solution, refer to the IFrame Integration Guide.

Base URL

https://partners.primeearn.com

Keep your app token secret. Never expose it in client-side JavaScript, mobile app source code, or public repositories. If your token is compromised, contact your account manager immediately to have it rotated.

Endpoints

Method	Path	Description
`GET`	`/{app_token}/api/v1/offers`	List available offers for a user
`GET`	`/{app_token}/api/v1/offers/active`	List active (started) offers for a user
`GET`	`/{app_token}/api/v1/offers/{hash}`	Get details for a single offer

Request Parameters

All three endpoints share the same parameters. Each endpoint section below only lists parameters that are unique to that endpoint.

Required Parameters

Parameter	Location	Type	Description
`app_token`	Path	string	Partner API token issued per app. Available in your publisher dashboard.
`app`	Query	string	App hash identifier for your integration.
`external_user_id`	Query	string	Your system’s unique identifier for the end user. Used for deduplication and reward attribution.
`output`	Query	string	Must always be set to `"API"`.
`ip`	Query	string	User’s IP address. Required so we can distribute users to geo-relevant campaigns.

Optional Parameters

Parameter	Type	Description
`maid`	string	Mobile Advertising ID. Pass the user’s IDFA (iOS) or GAID (Android) in this field. Must be provided if available — it significantly improves campaign match rates and attribution accuracy.
`birthday`	string	Date of birth in `YYYY-MM-DD` format. Preferred over `age` — use this whenever you have it.
`age`	integer	User age (`0–150`). Only use if `birthday` is not available.
`gender`	string	`m` (Male) or `f` (Female).
`zip`	string	Postal / ZIP code. Used for geo-targeted offer matching.
`source`	integer	Numeric traffic source identifier. Use the ID from the lookup table below.
`network`	integer	Numeric network identifier. Use the ID from the lookup table below.
`placement`	string	Describes where in your product the integration is placed (e.g. `post_level`, `main_menu`). Useful when you embed the wall in multiple locations and want to compare performance per placement.
`locale`	string	Interface language. Pass `en` or `en-US` to set the wall language to English. Currently only English is supported.

The more user attributes you provide, the better the offer targeting and match quality. maid must always be passed when available. When you have both birthday and age, only send birthday — it is more precise.

Source & Network ID Reference Pass the numeric ID as the value for both source and network. Choose the row that best describes how the user arrived in your app.

ID	Network	Source type
1	Google	Paid UA
2	Facebook	Paid UA
3	Instagram	Paid UA
4	Organic Google	Organic
5	Unknown	Other
6	Other	Other
7	Referral / Tell a friend	Organic
8	Apple Search Ads	Paid UA
9	TikTok Ads	Paid UA
10	Bidease	Paid UA
11	Mintegral	Paid UA
12	AppLovin	Paid UA
13	iOS organic	Organic
14	IronSource / Unity Ads	Paid UA
15	Moloco	Paid UA
16	Liftoff	Paid UA
17	Vungle	Paid UA
18	Email	Organic / Owned
19	Push notification	Organic / Owned

Quick Start

curl "https://partners.primeearn.com/{app_token}/api/v1/offers?app={APP_HASH}&external_user_id=user_abc123&ip={USER_IP}&platform=web&output=API"

A successful response returns HTTP 200:

{
  "data": []
}

GET /offers — List Available Offers

Returns all offers currently available for the given user to start.

GET /{app_token}/api/v1/offers

Additional parameters (this endpoint only):

Parameter	Type	Required	Description
`platform`	string	No	Filter offers by platform. Accepted values: `ios`, `android`, `web`.
`limit`	integer	No	Maximum number of offers to return.

Response

{
  "data": [
    {
      "id": "abc123",
      "title": "My Game",
      "icon": "https://cdn.example.com/icon.png",
      "large_image_url": "https://cdn.example.com/banner.png",
      "genre": "Action",
      "sub_genre": "RPG",
      "platforms": ["ios", "android"],
      "reward": 100,
      "tracking_url": "https://track.example.com/abc123",
      "ranking": 5,
      "cpi": 2.50,
      "package_name": "com.example.mygame"
    }
  ]
}

For now, we support image creatives only. large_image_url is available today, and a dedicated video URL will be added in a future version.

array

List of available offer objects.

Show Offer object fields

string

Unique offer identifier.

string

Display name of the app or game.

string

URL to the app icon.

string | null

URL to a banner or feature image. May be null — always check before rendering.

string | null

Top-level category (e.g. Action, Puzzle).

string | null

More specific category within genre.

array

Supported platforms for this offer. Values: ios, android.

number

Reward amount the user will earn, including any active bonus.

string

Unique click/tracking URL for this offer and user. Open this URL when the user taps the offer CTA.

integer | null

Offer rank. Lower numbers indicate higher priority. Use this to sort the offer list in your UI.

number

The revenue you receive (in USD) for a successful install. Only present on CPI-type offers.

string | null

The app’s bundle / package identifier (e.g. com.example.mygame). Can be used to identify a specific offer.

integer | null

ROAS performance score on the day of install (day 0). null if data is not yet available.

Value	Meaning
`1`	Actual ROAS is more than 25% below Target ROAS
`2`	Actual ROAS is between 10% and 25% below Target ROAS
`3`	Actual ROAS is within ±10% of Target ROAS
`4`	Actual ROAS is between 10% and 25% above Target ROAS
`5`	Actual ROAS is more than 25% above Target ROAS

integer | null

ROAS performance score at day 7. null if data is not yet available. Same 1–5 scale as performance_d0.

integer | null

ROAS performance score at day 30. null if data is not yet available. Same 1–5 scale as performance_d0.

GET /offers/active — List Active Offers

Returns offers the user has already started (i.e. clicked and installed). Uses the same parameters as /offers — no additional parameters.

GET /{app_token}/api/v1/offers/active

Response

{
  "data": [
    {
      "id": "def456",
      "title": "Installed App",
      "icon": "https://cdn.example.com/icon2.png",
      "large_image_url": null,
      "sub_genre": "Puzzle",
      "platforms": ["ios"],
      "reward": 80,
      "tracking_url": "https://track.example.com/def456",
      "status": "installed",
      "installation_time": "2026-05-20T10:30:00Z",
      "ranking": 3,
      "cpi": 0,
      "package_name": "com.example.installedapp"
    }
  ]
}

For now, we support image creatives only. large_image_url may be null, and a dedicated video URL will be added in a future version.

array

List of active offer objects.

Show Active offer object fields

string

Unique offer identifier.

string

Display name of the app or game.

string

URL to the app icon.

string | null

URL to a banner or feature image. May be null.

string | null

More specific category within genre.

array

Supported platforms for this offer.

number

Reward amount the user will earn.

string

Unique click/tracking URL for this offer and user.

string

Current status of this offer for the user. Value: installed.

string | null

ISO 8601 timestamp of when the user installed the app. null if not yet recorded.

integer | null

Offer rank for sorting purposes.

number

Revenue per successful install in USD. Only present on CPI-type offers.

string | null

The app’s bundle / package identifier. Can be used to identify a specific offer.

integer | null

ROAS performance score on the day of install (day 0). null if data is not yet available. Same 1–5 scale as the list endpoint.

integer | null

ROAS performance score at day 7. null if data is not yet available.

integer | null

ROAS performance score at day 30. null if data is not yet available.

GET /offers/ — Get Offer Details

Returns full details for a single offer, including instructions and individual reward tasks.

GET /{app_token}/api/v1/offers/{hash}

Additional parameters (this endpoint only):

Parameter	Location	Type	Required	Description
`hash`	Path	string	Yes	Offer hash identifier — the `id` field returned by the list endpoints.

Response

{
  "data": {
    "id": "abc123",
    "app_name": "My Game",
    "platform": ["ios", "android"],
    "ranking": 5,
    "genre": "Action",
    "sub_genre": "RPG",
    "icon": "https://cdn.example.com/icon.png",
    "large_image_url": "https://cdn.example.com/banner.png",
    "offer_description": "Complete level 20 to earn rewards.",
    "tracking_url": "https://track.example.com/abc123",
    "offer_status": null,
    "installation_time": null,
    "total_reward": 120,
    "instructions": {
      "steps": ["Download the app", "Reach level 20"],
      "offer_expiration_time": 10080
    },
    "rewards": [
      {
        "reward_amount": 120,
        "task": "Reach Level 20",
        "type": "iap",
        "reward_expiration_hours": 168
      }
    ],
    "cpi": 2.50,
    "package_name": "com.example.mygame"
  }
}

object

Full offer details object.

Show Offer details fields

string

Unique offer identifier.

string

Display name of the app or game.

array

Supported platforms for this offer (e.g. ["ios", "android"]).

integer | null

Offer rank for sorting purposes.

string | null

Top-level category.

string | null

More specific category within genre.

string

URL to the app icon.

string | null

URL to a banner or feature image. May be null.

string | null

Long-form description of the offer and its requirements.

string

Unique click/tracking URL for this offer and user. Open this URL when the user taps the offer CTA.

string | null

Click/install status for this user (e.g. pending, completed). null if the user has not yet interacted with this offer.

string | null

ISO 8601 timestamp of when the user clicked or installed the offer. null if not yet recorded.

number

Total reward the user can earn from this offer, excluding any active bonus.

object

Completion instructions and expiry details.

Show properties

array | null

Ordered list of human-readable steps the user must complete (e.g. ["Download the app", "Reach level 20"]).

integer | null

Maximum time in minutes from the first click within which all tasks must be completed.

array

Individual reward tasks for this offer.

Show Reward task fields

string

Human-readable description of the task (e.g. "Reach Level 20").

number

Points/currency awarded on completion of this task.

string

Task classification. Value: iap (requires an in-app purchase).

integer | null

Hours from first click within which this specific task must be completed. null if no per-task deadline applies.

number

Revenue per successful install in USD. Only present on CPI-type offers.

string | null

The app’s bundle / package identifier. Can be used to identify a specific offer.

integer | null

ROAS performance score on the day of install (day 0). null if data is not yet available. Same 1–5 scale as the list endpoint.

integer | null

ROAS performance score at day 7. null if data is not yet available.

integer | null

ROAS performance score at day 30. null if data is not yet available.

Error Responses

HTTP Status	Meaning
`200`	Success.
`400`	App not found or token mismatch. Check that `app_token` and `app` are correct.
`500`	Internal server error. Contact your account manager if this persists.

VPN Detected

When a user’s IP is identified as coming from a VPN or proxy, the API returns HTTP 200 with result: "error" and type: "vpn_detected". Display an error in your UI and ask the user to disable their VPN before retrying.

{
  "result": "error",
  "type": "vpn_detected",
  "surveys": null,
  "data": null,
  "message": null,
  "uhash": null,
  "log": null,
  "ff_configs": {
    "show_match_indicator": false,
    "increase_survey_card_rating": false,
    "use_horizontal_surveys_list": false,
    "use_locked_surveys": false,
    "use_next_survey": false,
    "hide_survey_estimated_time": false
  },
  "total": null
}

Check result === "error" and type === "vpn_detected" before rendering the offers list. Prompt the user to turn off their VPN or proxy and try again.

User Support

You can direct users to Prime Earn’s support pages for help with offers or to submit a support ticket. Substitute your real app-key and the user’s external_user_id in the links below:

Link	URL
FAQ	`https://monetize.primeearn.com/support?app={app-key}&uuid={external_user_id}`
Submit a support ticket	`https://monetize.primeearn.com/support-create-ticket?app={app-key}&uuid={external_user_id}`

The FAQ page automatically selects the language based on the user’s device locale.

​Rewarded Offers API

​Base URL

​Endpoints

​Request Parameters

​Required Parameters

​Optional Parameters

​Quick Start

​GET /offers — List Available Offers

​Response

​GET /offers/active — List Active Offers

​Response

​GET /offers/ — Get Offer Details

​Response

​Error Responses

​VPN Detected

​User Support

Rewarded Offers API

Base URL

Endpoints

Request Parameters

Required Parameters

Optional Parameters

Quick Start

GET /offers — List Available Offers

Response

GET /offers/active — List Active Offers

Response

GET /offers/ — Get Offer Details

Response

Error Responses

VPN Detected

User Support