JSON API (Offers list)

JSON API returns a full list of the inventory that we have at any moment, along with real-time pricing.

Request API

1a) Make client-side json call to


Example: http://api.virool.com/api/v1/offers/44fe67f.json?ip_address=

Or if you want to get all available offers and not just the best offer, add /all:


1b) Make server-side json call to


Or, if you want to get all available offers, not just the best single offer, add /all:


Example: http://api.virool.com/api/v1/offers/44fe67f/all.json?ip_address=

You can use additional parameters:

Key Type Example value Comment
key String 8a70422 Site key
userId String 12341 Internal user ID in your app
String IP address of your visitor. Use this param to get the right selection of offers while making a server-side call to API.
String male, female Gender of user
String YYYY-MM-DD (e.g. 1987-10-25) Date of birth
Integer 640 Frame width in pixels, min value: 290. Default value 640
Integer 360 Frame height in pixels, min value is 190. Default value 360
Integer 21314231521 Dynamic parameter to prevent request from being cached
Integer 1 or 0 When 1, the widget will show only auto-play campaigns. When 0, the widget will show only click-to-play campaigns.

Example Response

  "data": {
     "status": "OK",
     "offer": { 
       "title": "Havaianas",
       "description": "Please watch this short video to earn 6 Gems",
       "campaignId": 4353,
       "offerImg": "http://img.youtube.com/vi/tsHPj4g4XJw/0.jpg",
       "currencyName": "Gems",
       "reward": 6,
       "rewardText": "6 Gems",
       "offerType": "video",
       "offerLength": 13,
       "viewsToDeliver": 3743,
       "targetGender": "a",
       "targetAgeGroups": "0",
       "targetPlatforms": ["blogs","mobile","social"],
       "targetSystems": ["mobile-android","mobile-ios","desktop-all"],
       "targetCountries": ["US","CA","GB","DE","BR","FR"],
       "keywords": ["indie rock","alternative music","rock music","concert","music"],
       "width": 640,
       "height": 360,
       "url": "http://api.virool.com/widgets/8a70422e3377ef60fa4610eefb111111/4353?suid=12341height=360&width=640",
       "mobileUrl": "http://api.virool.com/widgets/mobile_offer/8a70422e3377ef60fa4610eefb111111/4353?suid=12341&height=190&width=290",

Response Body:

Key Type Description
status String Request status: "OK" or "FAIL"
title String Offer title. Example: "Havaianas"
description String Offer short description. Example: "Please watch this short video to earn 6 Gems"
descriptionFull String Offer full description. Example: "Alice and Bob performing live concert"
campaignId Integer Offer ID. Example: 4353
offerImg String Link to offer thumbnail image. Example: "http://img.youtube.com/vi/tsHPj4g4XJw/0.jpg"
currencyName String Virtual currency name. Example: "Gems"
reward Integer Offer reward in cents. Example: 6
rewardText String Offer reward text. Example: "6 Gems"
offerType String Offer type. Always "video"
offerLength Integer Video length in seconds. Example: 13
viewsToDeliver Integer How many times offer can be viewed until promotion will be stopped. Example: 3743
targetGender String Offer gender targeting: "a" - All, "m" - Men, "f" - Female. Example: "a"
targetAgeGroups String Offer age targeting: "0" - All, "1" - "Under 13", "2" - "14-17", "3" - "18-24", "4" - "25-34", "5" - "35-44", "6" - "45-54", "7" - "55-64", "8" - "Over 65". Example: "0"
targetPlatforms Array Offer platform targeting. Options: ["blogs","mobile","social","virtual_currency","games"]
targetSystems Array Offer device targeting. Options: ["mobile-android, mobile-ios, mobile-other, desktop-all, mobile-all"]
targetCountries Array Country, city/state or DMA targeting. Array of values: "country-code" or "country-code/state/" or "country-code/state/city" or "US/DMA/dma-code" (US only). Example for countries: ["US", "BR"]. Example of state targeting, Oregon, US: ["US/OR/]. Example of city targeting: ["US/CA/San Francisco"]. Example of DMA targeting: ["US/DMA/807"] where "807" is DMA code of "San Francisco-Oakland-San Jose, CA" metropolian area. More info about DMA regions: https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions
targetCategories Array Offer category. Options: ["alcohol", "auto", "brands", "documentary", "fashion", "games", "health", "kickstarter", "movies", "music", "technology", "travel", "show"]
keywords Array Keywords that describe offer content. Example: ["indie rock","concert","music"]
width Integer Video width. Example: 640
height Integer Video height. Example: 360
url String Link to offer widget that can be embedded with iframe. Example: "http://api.virool.com/widgets/8a70422e3377ef60fa4610eefb111111/4353?suid=12341height=360&width=640"
mobileUrl String Link to offer mobile widget. Example: "http://api.virool.com/widgets/mobile_offer/8a70422e3377ef60fa4610eefb111111/4353?suid=12341&height=190&width=290"

See our tutorial for virtual currency integration.

Client side integration examples

The code below gets offers from our JSON API and sends alerts on the offers count:

Replace 44fe67f with your site key

Fully-working offerwall made on top of our JSON API

Demo: http://api.virool.com/offers/wall/44fe67f?ip_address=

Replace 44fe67f with your site key

Server-side integration examples

To make a server-side request to our API, you must provide us with the IP address of your user/client/visitor. Here are a few examples: