Bulk API
From wiki.taptica.com
Taptica Bulk API allows you to pull the offers Meta data from our servers, the offers inventory will be associated with your account by Taptica account managers.
Since there are frequent changes in the production offers list,The publisher is responsible to generate the request every hour. In case an offer was returned in a previous response and is no longer in the response, it means you have to Remove the offer from production.
Taptica is limiting the numbers of daily requests per country,once you exceed 3000 requests you will not get response.
Request
• The request is sent via an HTTP "Get request" to the following URL: https://api.taptica.com/v2/bulk?
• The body of the POST contains URL encoded key/value pairs separated by "&".
Request parameters
| Parameter | Name In Request | Description | Example | RMandatory |
| token | Token | Your Taptica private token | Token=hSuz7l0OUjwVy4uGX2bfAw%3d%3d | Yes |
| platforms | Platforms | Indicate the Platform of the requested offers. Can be either iPhone, iPad, iPod, Android. | platforms=iPhone | Yes |
| Countries | countries | Enter the country codes of the requested offers. Can be multiple selection.Note sometimes you won't get a response if Taptica dosen't have an offer for the specified country. | countries=US,BG | No |
| payout Type | payoutType | Specifies the requested offer payout. Can be either CPA, CPC, CPM. Mostly, Taptica supports CPA offers. | payoutType=cpa | No |
| minPayout | Min Payout | Specifies the minimum payout offer you would like to get in the response. (if you do not want to filter by country leave it empty) | minPayout=1.2 | No |
| categories | Categories | Specifies the offer categories you would like to get in the response. | categories=Games,Travel and Local, | No |
| version | Version | Add additional data to the response as offer ID | version=1 | No |
| noCreative | No creative | No creative allow the publisher to decide if the response will include the creative or won't (the value can be false or true) | noCreative=True | No |
| size | Creative size | allow the publisher to decide which creative size will be include in the response (in case he wise to get specific banner size) | size=320X480,320X50,728X90 | No |
| format | Format | Specifies the response type. json(Default),jsonp,xml,csv. | xml, csv, json,jsonp | No |
| callback | JSONP callback | Specifies the callback you will get in the jsonp response | what ever is your callback (for example callback=runme) | no |
Response
Response parameters
| Parameter | Description | Example |
| OfferId | Taptica internal offer ID. | 4960 |
| Offer Name | Taptica internal offer name. | Underworld Empire- US- iPhone |
| Description | Offer description. | Play with MILLIONs of players NOW in the LARGEST, most INTENSE, SOCIAL CRIME MMO! |
| Platform | Supported platform. | iPhone |
| MinOsVersion | Minimum OS version. | 4.3 |
| MarketAppId | Google / Appstore application id. | 555150599 |
| PreviewLink | Link to the application in Appstore. | https://itunes.apple.com/us/app/underworld-empire/id555150599 |
| TrackingLink | Taptica basic tracking link *(please see explanation below) | http://clk.taptica.com/aff_c?tt_ls=b&offer_id=19604&aff_id=3125018&tt_appid=test&tt_bannerid=123554 |
| IsDeviceIdMandatory | when set to true, it means that the application must get at least one of the device parameters specified in the "DeviceIds". | false / true |
| DeviceIds | Indicates the offer supporeted device id, in case the IsDeviceIdMandatory is true, Taptica must get at least one of the devie parameters. (returen as list). | tt_mac,tt_mac_sha1,tt_mac_md5,tt_idfa,tt_idfa_sha1,tt_idfa_md5 |
| SupportedCountries | Indicates the offer's supported countries (returned as list). | US |
| PayoutType | Indicates the offer Payout Type, can be either CPA, CPC, CPM. | CPA |
| Payout | Indicates the offer Payout. | 1.2 |
| DailyBudget | Returns the remaining budget for specific publisher in US Dollars or return unavailable when there is no limit. | Unlimited / 1500 |
| Category | Shows the offer categories as sets in Taptica system (returned as list). | Entertainment / Games |
| Creative | provides the creative data as Banner ID, Banner Name, Creative Link, Creative Type, Creative Size. (returned as list) |
Id 49552 Name 20130327115527-DJ_Tira_static_Banner_320X320.gif CreativeLink http://media.go2speed.org/brand/files/taptica/3530/20130327115527-DJ_Tira_static_Banner_320X320.gif CreativeType banner CreativeSize 320x320 |
| BlockedSubAffiliate | Unauthorized sub affiliate, Specifies the sub affiliate of the affiliate which are unauthorized to run the offer. | Unavailable / 1265 ... |
| BannerText | Offer promotion text. | Get Free Application Now! |
| AppIconURL | link to the application Icon on app store or Google play | https://lh6.ggpht.com/LmBa6jgU5zTnvb4G52ZYeCr2CAq8BEB9atNBTGkyZXIsEZTjxDA_F7YV6l1t9gpBEw=w300-rw |
| AppProviderName | The Application Provider Name | Playtika LTD |
| AppName | The application official name as it on app store or Google play | Candy Crush Sega |
- The tracking link should be a combination of the response you get in the "TrackingLink" + Bannerid + "DeviceIds" for example:
| Parameter | Description | Example |
| Affiliate click ID | Used for click id that the publisher may want to send Taptica and get back via S2S postback (alfa numeric) | tt_aff_clickid=qa143287w |
| Sub affiliate | Used for sending Taptica your sub affiliate id upon click. The publisher can get it back via S2S postback (alfa numeric) | tt_sub_aff=13461d46 |
| Affiliate impression ID | Used for impression id that the publisher may want to send Taptica and get back via S2S postback (alfa numeric) | tt_aff_impid=1321sads35sa |
| Pipeline Data | Used for any information that the publisher may want to send Taptica upon click and get back via S2S postback (alfa numeric) | pd=abcd1234 |
Taptica Device Keys
| Parameter | Name In Request | Description | Example | Daynamic? |
| IMEI | tt_imei | Use for send Taptica Plain IMEI or when you don’t know what is the format of IMEI you have. | tt_imei=86453214567892 | Yes |
| IMEI SHA1 | tt_imei_sha1 | Use for send Taptica IMEI in SHA1 format | tt_imei_sha1=35eb6d1fc48b502e239b6449e9df534e415cad95 | Yes |
| IMEI MD5 | tt_imei_md5 | Use for send Taptica IMEI in MD5 format | tt_imei_md5=946cc1baf8bcaec827bb1828cc6d9a94 | Yes |
| Android Advertising ID | tt_advertising_id | Use for send Taptica Android advertising plain ID | tt_advertising_id=3ee0149b4ccef71bs85d24derg | Yes |
| Android Advertising ID SHA1 | tt_advertising_id_sha1 | Use for send Taptica Android advertising ID in SHA1 format | tt_advertising_id=32f2e52e8157fcb729d799d1ca69160df2edf8974 | Yes |
| Android Advertising ID MD5 | tt_advertising_id_md5 | Use for send Taptica Android advertising ID in MD5 format | tt_advertising_id=2315w52e8157fcb729d799d1ca691608speofd2 | Yes |
| Mac Address | tt_mac | Use for send Taptica Plain Mac Address or when you don’t know what is the format of the Mac Address you have. (upper case with colon) | tt_mac=44:2A:60:G5:GE:G5 | Yes |
| Mac Address SHA1 | tt_imei_sha1 | Use for send Taptica Mac Address in SHA1 format (upper case with colon) | tt_mac_sha1=fa6bb084ae52461328eb9f06039be222ef287246 | Yes |
| Mac Address MD5 | tt_mac_md5 | Use for send Taptica Mac Address in MD5 format (upper case with colon) | tt_mac_md5=80efe2256d548c85ca2f2d18de241a80 | Yes |
| IDFA | tt_idfa | Use for send Taptica Plain IDFA or when you don’t know what is the format of IDFA you have. | tt_idfa=771468523E3346ABAA04E207BBAF094B | Yes |
| IDFA SHA1 | tt_idfa_sha1 | Use for send Taptica IDFA in SHA1 format | tt_idfa_sha1=ee5c19f8cf370b5978f4b9f33343a5e79c58df9a | Yes |
| IDFA MD5 | tt_idfa_md5 | Use for send Taptica IDFA in MD5 format | tt_idfa_md5=bb1e0285fbb97ba83fdb4e72514d62f5 | Yes |
Category List
The optional categories names are:
| games |
| Communications |
| Entertainment |
| Financial Services |
| Health and Fitness |
| Shopping and Retail |
| Social |
| Sports |
| Travel and Local |
| Multimedia |
| Automotive |
| Books and Reference |
| Lifestyle |
| Kids |
| Gambling |
| Education |
| News and weather |
Error messages
| Error Code | Error Text | Error description |
| 0 | OK | Success |
| 100 | Not Modified. | There was no data to return, please try again. if consist please contact Taptica Support |
| 200 | Bad Request. | Bad Request for parameter + the bad parameter for example platform with value iPhtone |
| 300 | Unauthorized. | Authorization error. Authentication credential are missing or incorrect. |
| 301 | Invalid Token. | The token that was delivered is invalid |
| 400 | General Error. | Any other error that does not fall under the above errors |
Sample MXL Response
<BulkApi>
<error>OK</error> <errorCode>0</errorCode> <Offer> <OfferId>14943</OfferId> <OfferName>Test Offer Black - iPhone</OfferName> <OfferDescription>Test Offer Black - iPhone</OfferDescription> <SupportedPlatform>IPhone</SupportedPlatform> <SupportedPlatform>IPod</SupportedPlatform> <MinimumOSVersion>4</MinimumOSVersion> <MarketAppId>Test Offer Black</MarketAppId> <PreviewLink> https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8 </PreviewLink> <TrackingLink> http://tracking.taptica.com/aff_c?tt_ls=b&offer_id=14943&aff_id=3125018&tt_appid=Test_Offer_Black&tt_bannerid= </TrackingLink> <DeviceIdMandatory>false</DeviceIdMandatory> <BlockedSubAffiliate>Unavailable</BlockedSubAffiliate> <SupportedCountry>US</SupportedCountry> <SupportedCountry>GB</SupportedCountry> <SupportedCountry>AE</SupportedCountry> <SupportedCountry>IL</SupportedCountry> <Network>WIFI</Network> <Network>3G</Network> <PayoutType>CPA</PayoutType> <Payout>0.00000</Payout> <DailyBudget>Unlimited</DailyBudget> <Category>games</Category> <Category>multimedia</Category> <Category>automotive</Category> <Category>books and reference</Category> <Category>lifestyle</Category> <Category>kids</Category> <Category>gambling</Category> <Category>education</Category> <Category>news and weather</Category> <Category>communications</Category> <Category>entertainment</Category> <Category>financial services</Category> <Category>health and fitness</Category> <Category>shopping and retail</Category> <Category>social</Category> <Category>sports</Category> <Category>travel and local</Category> <Creative> <Id>177192</Id> <Name>300X250_black_animated.gif</Name> <CreativeLink> http://76b3ceeab4c855fb9953-3bebc903fd41a20c171fdfefdfe53008.r84.cf2.rackcdn.com/14943/20140616/d1a2268bb8504e8481acaf6678affbe2_300X250_black_animated.gif </CreativeLink> <CreativeType>FullScreen</CreativeType> <CreativeSize>300x250</CreativeSize> </Creative> <Creative> <Id>106245</Id> <Name>Dragon1.mp4</Name> <CreativeLink> http://76b3ceeab4c855fb9953-3bebc903fd41a20c171fdfefdfe53008.r84.cf2.rackcdn.com/14943_da8e34ec13d14419b5dca863fad45657_Dragon1.mp4 </CreativeLink> <CreativeType>Video</CreativeType> <CreativeSize>320x480</CreativeSize> </Creative> </Offer>
</BulkApi>
