# Offers API

*<mark style="color:red;">**Make sure your API is active before reading this documentation.**</mark>*

## API

Method: **GET or POST**

Base URL: `https://revtoo.com/api/offers/`

| Parameter | Description                                  | Type   |
| --------- | -------------------------------------------- | ------ |
| api\_key  | Your API Key, get it from your app placement | String |

Optional Parameters

| Parameter | Description                                    | Type    | Default       |
| --------- | ---------------------------------------------- | ------- | ------------- |
| countries | Comma-separated list of 2-letter country codes | String  | All countries |
| user\_id  | Your user unique identifier                    | String  | \[USER\_ID]   |
| limit     | Number of offers per page                      | Integer | Unlimited     |
| page      | Pagination page number                         | Integer | 1             |

{% hint style="info" %}
If you use "page" then you must have to use "limit", otherwise you'll face a status 103 error.
{% endhint %}

**Example Request:** `GET https://revtoo.com/api/offers/?api_key=YOUR_API_KEY&user_id=USER_ID&countries=US,CA,DE&limit=100&page=1`&#x20;

<mark style="color:green;">**OR**</mark>

**Example Request (Use form-data request body)**: `POST https://revtoo.com/api/offers/`

## Responses

### A successful response

```json
{
  "success": true,
  "status": 200,
  "reward_value": 60,
  "reward_name": "Points",
  "reward_round": 2,
  "total_offers": 10,
  "shown_offers": 2,
  "offers": [
    {
      "id": 1,
      "hasEvents": false,
      "featured": false,
      "title": "Pokemon GO",
      "description": "Start a 14 Day Free Trial (New Users Only)",
      "payout": 1.96,
      "reward": 117.6,
      "url": "https://revtoo.com/redirect?api_key=YOUR_API_KEY&offer_id=1&user_id=USER_ID",
      "image": "https://play-lh.googleusercontent.com/eftfcMyaaRruAiGPgVZ4rkBsKU_s6qNswWuIOpF7PCNcsd2pY1vhkYnYEKdszfLfTu4=s96-rw",
      "category": "offer",
      "countries": [
        "BE",
        "FR",
        "NL"
      ],
      "os": [
        "web",
        "android",
        "ios"
      ],
      "timestamp": 1737321735,
      "events": []
    },
    {
      "id": 2,
      "hasEvents": true,
      "featured": false,
      "title": "Puzzles & Survival",
      "description": "Purchase Scarlett Pack 2 (Min. $9.99, New Users Only)",
      "payout": 21,
      "reward": 1260,
      "url": "https://revtoo.com/redirect?api_key=YOUR_API_KEY&offer_id=2&user_id=USER_ID",
      "image": "https://play-lh.googleusercontent.com/NeANdRQlPAh2vgZW1oU0_6teTt8tsJwiJoYXE5SRjRoqdbJP_3wJxIIRcViSti-1qGV0=w480-h960-rw",
      "category": "offer",
      "countries": [
        "AU"
      ],
      "os": [
        "android"
      ],
      "timestamp": 1737321735,
      "events": [
        {
          "event_id": "65105-1",
          "event_title": "install_game",
          "event_description": "Install the game and play for 1 minute",
          "event_payout": 1,
          "event_reward": 60
        },
        {
          "event_id": "65105-10",
          "event_title": "buy_scarlett2_pack",
          "event_description": "Purchase Scarlett Pack 2 ($9.99)",
          "event_payout": 21,
          "event_reward": 1260
        }
      ]
    }
  ],
  "pagination": {
    "limit": 2,
    "page": 1
  }
}
```

{% hint style="info" %}
The “**payout, reward**” can have two possible values:

1\. An asterisk (\*) to indicate that the payout and reward values are **variable**.

2\. A number (e.g., 12.32, 432.12, 233) to represent a fixed payout, reward amount.

[See example below.](#an-example-with-asterisk-payout-response)
{% endhint %}

### An example with asterisk payout response

```json
{
  "success": true,
  "status": 200,
  "reward_value": 60,
  "reward_name": "Points",
  "reward_round": 2,
  "total_offers": 10,
  "shown_offers": 1,
  "offers": [
    {
      "id": 1970,
      "hasEvents": false,
      "featured": true,
      "title": "Pollfish Surveys",
      "description": "Complete a survey and earn reward, can be completed multiple times a day.",
      "payout": "*", // Explains it have variable payout
      "reward": "*", // Explains it have variable reward
      "url": "https://revtoo.com/redirect?api_key=YOUR_API_KEY&offer_id=pollfish&user_id=[USER_ID]",
      "image": "https://gdm-catalog-fmapi-prod.imgix.net/ProductLogo/b4ee8bec-dcea-4f03-8bb8-9b3398e9dccd.jpeg?auto=format%2Ccompress&fit=max&w=256&q=75&ch=Width%2CDPR",
      "category": "survey",
      "countries": [
        "US",
        "UK",
        "DE"
      ],
      "os": [
        "android", "ios", "web"
      ],
      "timestamp": 1737440432,
      "events": []
    }
  ],
  "pagination": {
    "limit": 1,
    "page": 1
  }
}
```

### Response Root Structure

```json
{
  "success": true,
  "status": 200,
  "reward_value": 60,
  "reward_name": "Points",
  "reward_round": 2,
  "total_offers": 100,
  "shown_offers": 10,
  "offers": [ ... ], // The core offers data is contained here, let's learn this.
  "pagination": {
    "limit": 10,
    "page": 1
  }
}
```

### Offer Object

| Key         | Type              | Description                 | Example                                                                                                                                                                                  |
| ----------- | ----------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id          | Integer           | Unique offer identifier     | 123                                                                                                                                                                                      |
| hasEvents   | Boolean           | Whether offer has events    | true/false                                                                                                                                                                               |
| featured    | Boolean           | If offer is featured        | true/false                                                                                                                                                                               |
| title       | String            | Offer title                 | Pokemon GO - A World of Pokemons                                                                                                                                                         |
| description | String            | Offer description           | Join Trainers around the world and play *Pokémon GO* together in new and exciting ways.                                                                                                  |
| payout      | Float/String (\*) | Offer payout amount         | 12.05                                                                                                                                                                                    |
| reward      | Float/String (\*) | Calculated reward amount    | 6025                                                                                                                                                                                     |
| url         | String            | Tracking redirect URL       | [https://revtoo.com/api/offers/?api\_key=YOUR\_API\_KEY\&offer\_id=OFFER\_ID\&user\_id=USER\_ID](https://revtoo.com/api/offers?api_key=YOUR_API_KEY\&offer_id=OFFER_ID\&user_id=USER_ID) |
| image       | String            | Offer image URL             | <https://revtoo.com/path/to/image>                                                                                                                                                       |
| category    | String            | Offer category              | offer/survey                                                                                                                                                                             |
| countries   | Array             | Supported countries         | \["US", "CA", "DE"]                                                                                                                                                                      |
| os          | Array             | Supported operating systems | \["andorid", "ios", "web"]                                                                                                                                                               |
| timestamp   | Integer           | Offer creation timestamp    | 1737778104                                                                                                                                                                               |
| events      | Array             | Offer-specific events       | Please refer to [#a-successful-response](#a-successful-response "mention")                                                                                                               |

### Error Responses (status with message field)

| Status | Code                | Message                       |
| ------ | ------------------- | ----------------------------- |
| 100    | Missing API Key     | No API key provided           |
| 101    | Invalid API Key     | API key not found in database |
| 102    | Rate Limit Exceeded | Too many requests             |
| 103    | Pagination Error    | Page specified without limit  |
| 105    | Country Code Error  | No valid country codes        |

## Example Requests (GET)

### Get All Active Offers

```
GET https://revtoo.com/api/offers/?api_key=YOUR_API_KEY
```

### Filter by Countries

```
GET https://revtoo.com/api/offers/?api_key=YOUR_API_KEY&countries=US,CA,UK
```

### Paginated Offers

```
GET https://revtoo.com/api/offers/?api_key=YOUR_API_KEY&limit=10&page=2
```

## Example Requests (POST)

### Get All Active Offers

```
POST https://revtoo.com/api/offers/

// FORM-DATA (REQUEST BODY)
{
"api_key" = "YOUR_API_KEY"
}
```

### Filter by Countries

```
POST https://revtoo.com/api/offers/

// FORM-DATA (REQUEST BODY)
{
"api_key" = "YOUR_API_KEY",
"countries" = "US,CA,UK"
}
```

### Paginated Offers

```
POST https://revtoo.com/api/offers/

// FORM-DATA (REQUEST BODY)
{
"api_key" = "YOUR_API_KEY",
"countries" = "US,CA,UK",
"limit" = 10,
"page" = 2
}
```

{% hint style="info" %}
We only tried to visualize the REQUEST BODY in [Example Requests (POST)](#example-requests-post), be aware that actual code may vary.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.revtoo.com/api/offers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.