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

http://api.virool.com/api/v1/offers/[YOUR_SITEKEY].json?userId=[VISITOR_ID]

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

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

http://api.virool.com/api/v1/offers/[YOUR_SITEKEY]/all.json?userId=[VISITOR_ID]

1b) Make server-side json call to

http://api.virool.com/api/v1/offers/[YOUR_SITEKEY].json?userId=[VISITOR_ID]&ip_address=[VISITOR_IP]

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

http://api.virool.com/api/v1/offers/[YOUR_SITEKEY]/all.json?userId=[VISITOR_ID]&ip_address=[VISITOR_IP]

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

You can use additional parameters:

Key Type Example value Comment
key String 8a70422 Site key
userId String 12341 Internal user ID in your app
ip_address
(optional)
String 74.125.224.132 IP address of your visitor. Use this param to get the right selection of offers while making a server-side call to API.
gender
(optional)
String male, female Gender of user
dob
(optional)
String YYYY-MM-DD (e.g. 1987-10-25) Date of birth
width
(optional)
Integer 640 Frame width in pixels, min value: 290. Default value 640
height
(optional)
Integer 360 Frame height in pixels, min value is 190. Default value 360
d
(optional)
Integer 21314231521 Dynamic parameter to prevent request from being cached
filter_autoplay
(optional)
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=8.8.8.8

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: