> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primeearn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rewarded Offers API

> Programmatically fetch, display, and track rewarded game offers using the Prime Earn Partner API. Full reference for all three endpoints, request parameters, response fields, and error codes.


# Rewarded Offers API

<Info>**Version 1.3** — added `performance_d0`, `performance_d7`, `performance_d30` fields to offer objects. See the [changelog](./changelog) for details.</Info>

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](./iframe), the API gives you full control over the presentation layer while Prime Earn handles offer sourcing, reward logic, and attribution.

<Info>
  **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](./iframe).
</Info>

***

## Base URL

```
https://partners.primeearn.com
```

<Danger>
  **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.
</Danger>

***

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

<Tip>
  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.
</Tip>

**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

```bash theme={null}
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`:

```json theme={null}
{
  "data": []
}
```

***

## GET /offers — List Available Offers

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

```http theme={null}
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

```json theme={null}
{
  "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"
    }
  ]
}
```

<Note>
  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.
</Note>

<ResponseField name="data" type="array">
  List of available offer objects.

  <Expandable title="Offer object fields">
    <ResponseField name="id" type="string">
      Unique offer identifier.
    </ResponseField>

    <ResponseField name="title" type="string">
      Display name of the app or game.
    </ResponseField>

    <ResponseField name="icon" type="string">
      URL to the app icon.
    </ResponseField>

    <ResponseField name="large_image_url" type="string | null">
      URL to a banner or feature image. May be `null` — always check before rendering.
    </ResponseField>

    <ResponseField name="genre" type="string | null">
      Top-level category (e.g. `Action`, `Puzzle`).
    </ResponseField>

    <ResponseField name="sub_genre" type="string | null">
      More specific category within genre.
    </ResponseField>

    <ResponseField name="platforms" type="array">
      Supported platforms for this offer. Values: `ios`, `android`.
    </ResponseField>

    <ResponseField name="reward" type="number">
      Reward amount the user will earn, including any active bonus.
    </ResponseField>

    <ResponseField name="tracking_url" type="string">
      Unique click/tracking URL for this offer and user. Open this URL when the user taps the offer CTA.
    </ResponseField>

    <ResponseField name="ranking" type="integer | null">
      Offer rank. Lower numbers indicate higher priority. Use this to sort the offer list in your UI.
    </ResponseField>

    <ResponseField name="cpi" type="number">
      The revenue you receive (in USD) for a successful install. Only present on CPI-type offers.
    </ResponseField>

    <ResponseField name="package_name" type="string | null">
      The app's bundle / package identifier (e.g. `com.example.mygame`). Can be used to identify a specific offer.
    </ResponseField>

    <ResponseField name="performance_d0" type="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       |
    </ResponseField>

    <ResponseField name="performance_d7" type="integer | null">
      ROAS performance score at day 7. `null` if data is not yet available. Same 1–5 scale as `performance_d0`.
    </ResponseField>

    <ResponseField name="performance_d30" type="integer | null">
      ROAS performance score at day 30. `null` if data is not yet available. Same 1–5 scale as `performance_d0`.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## GET /offers/active — List Active Offers

Returns offers the user has already started (i.e. clicked and installed). Uses the same parameters as [/offers](#get-offers--list-available-offers) — no additional parameters.

```http theme={null}
GET /{app_token}/api/v1/offers/active
```

### Response

```json theme={null}
{
  "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"
    }
  ]
}
```

<Note>
  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.
</Note>

<ResponseField name="data" type="array">
  List of active offer objects.

  <Expandable title="Active offer object fields">
    <ResponseField name="id" type="string">
      Unique offer identifier.
    </ResponseField>

    <ResponseField name="title" type="string">
      Display name of the app or game.
    </ResponseField>

    <ResponseField name="icon" type="string">
      URL to the app icon.
    </ResponseField>

    <ResponseField name="large_image_url" type="string | null">
      URL to a banner or feature image. May be `null`.
    </ResponseField>

    <ResponseField name="sub_genre" type="string | null">
      More specific category within genre.
    </ResponseField>

    <ResponseField name="platforms" type="array">
      Supported platforms for this offer.
    </ResponseField>

    <ResponseField name="reward" type="number">
      Reward amount the user will earn.
    </ResponseField>

    <ResponseField name="tracking_url" type="string">
      Unique click/tracking URL for this offer and user.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of this offer for the user. Value: `installed`.
    </ResponseField>

    <ResponseField name="installation_time" type="string | null">
      ISO 8601 timestamp of when the user installed the app. `null` if not yet recorded.
    </ResponseField>

    <ResponseField name="ranking" type="integer | null">
      Offer rank for sorting purposes.
    </ResponseField>

    <ResponseField name="cpi" type="number">
      Revenue per successful install in USD. Only present on CPI-type offers.
    </ResponseField>

    <ResponseField name="package_name" type="string | null">
      The app's bundle / package identifier. Can be used to identify a specific offer.
    </ResponseField>

    <ResponseField name="performance_d0" type="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.
    </ResponseField>

    <ResponseField name="performance_d7" type="integer | null">
      ROAS performance score at day 7. `null` if data is not yet available.
    </ResponseField>

    <ResponseField name="performance_d30" type="integer | null">
      ROAS performance score at day 30. `null` if data is not yet available.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## GET /offers/{hash} — Get Offer Details

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

```http theme={null}
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

```json theme={null}
{
  "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"
  }
}
```

<ResponseField name="data" type="object">
  Full offer details object.

  <Expandable title="Offer details fields">
    <ResponseField name="id" type="string">
      Unique offer identifier.
    </ResponseField>

    <ResponseField name="app_name" type="string">
      Display name of the app or game.
    </ResponseField>

    <ResponseField name="platform" type="array">
      Supported platforms for this offer (e.g. `["ios", "android"]`).
    </ResponseField>

    <ResponseField name="ranking" type="integer | null">
      Offer rank for sorting purposes.
    </ResponseField>

    <ResponseField name="genre" type="string | null">
      Top-level category.
    </ResponseField>

    <ResponseField name="sub_genre" type="string | null">
      More specific category within genre.
    </ResponseField>

    <ResponseField name="icon" type="string">
      URL to the app icon.
    </ResponseField>

    <ResponseField name="large_image_url" type="string | null">
      URL to a banner or feature image. May be `null`.
    </ResponseField>

    <ResponseField name="offer_description" type="string | null">
      Long-form description of the offer and its requirements.
    </ResponseField>

    <ResponseField name="tracking_url" type="string">
      Unique click/tracking URL for this offer and user. Open this URL when the user taps the offer CTA.
    </ResponseField>

    <ResponseField name="offer_status" type="string | null">
      Click/install status for this user (e.g. `pending`, `completed`). `null` if the user has not yet interacted with this offer.
    </ResponseField>

    <ResponseField name="installation_time" type="string | null">
      ISO 8601 timestamp of when the user clicked or installed the offer. `null` if not yet recorded.
    </ResponseField>

    <ResponseField name="total_reward" type="number">
      Total reward the user can earn from this offer, excluding any active bonus.
    </ResponseField>

    <ResponseField name="instructions" type="object">
      Completion instructions and expiry details.

      <Expandable title="properties">
        <ResponseField name="steps" type="array | null">
          Ordered list of human-readable steps the user must complete (e.g. `["Download the app", "Reach level 20"]`).
        </ResponseField>

        <ResponseField name="offer_expiration_time" type="integer | null">
          Maximum time in **minutes** from the first click within which all tasks must be completed.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rewards" type="array">
      Individual reward tasks for this offer.

      <Expandable title="Reward task fields">
        <ResponseField name="task" type="string">
          Human-readable description of the task (e.g. `"Reach Level 20"`).
        </ResponseField>

        <ResponseField name="reward_amount" type="number">
          Points/currency awarded on completion of this task.
        </ResponseField>

        <ResponseField name="type" type="string">
          Task classification. Value: `iap` (requires an in-app purchase).
        </ResponseField>

        <ResponseField name="reward_expiration_hours" type="integer | null">
          Hours from first click within which this specific task must be completed. `null` if no per-task deadline applies.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cpi" type="number">
      Revenue per successful install in USD. Only present on CPI-type offers.
    </ResponseField>

    <ResponseField name="package_name" type="string | null">
      The app's bundle / package identifier. Can be used to identify a specific offer.
    </ResponseField>

    <ResponseField name="performance_d0" type="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.
    </ResponseField>

    <ResponseField name="performance_d7" type="integer | null">
      ROAS performance score at day 7. `null` if data is not yet available.
    </ResponseField>

    <ResponseField name="performance_d30" type="integer | null">
      ROAS performance score at day 30. `null` if data is not yet available.
    </ResponseField>
  </Expandable>
</ResponseField>

***

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

```json theme={null}
{
  "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
}
```

<Warning>
  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.
</Warning>

***

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