# 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 %}