Static Offer API
General Concept
The static offer API is designed to be called by a backend/server. This API returns you the inventory of all currently available offers. The feed can be used to extend your existing offer inventory or build your own offer system.
It is to be noted that the static offer API was not designed to be used in combination with any of the user-based offer APIs that we provide.
Target Group or Use Case: Use this API to grab our inventory and insert the offers in your existing offer management system.
Calling the API
You have to enable Offers for the App via our Publisher Dashboard
By calling the Get Offers for Publishers Endpoint, you will get all the offers available in the BitLabs network. You are then free to use your own yield management.
Example response
{
"data": {
"offers": [
{
"anchor": "Path Crypto",
"app_metadata": {
"app_id": "6449375736",
"categories": [
"Finance"
],
"screenshot_urls": [
"https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/58/d9/76/58d97639-1df4-7ad4-a4a4-647cd6fa22ed/1f219fda-97fa-4533-8a10-28e764f5a0a0_5.5___1242x2208__U00281_U0029__U00282_U0029.jpg/626x0w.jpg",
"https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/e5/23/41/e523411e-9536-d5d2-5977-2382b8c5e713/6438e989-33b0-47eb-b8d6-744275b709ad_5.5___1242x2208__U00282_U0029__U00282_U0029.jpg/626x0w.jpg",
"https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/25/25/fb/2525fb00-f103-babc-5997-d29953bece89/152275b2-16da-4d39-9263-0f8fa63c03cd_5.5___1242x2208__U00282_U0029__U00283_U0029.jpg/626x0w.jpg",
"https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/2c/51/55/2c515557-6162-1aa9-6fe2-42bddee60915/2442bd92-f34d-4b09-9df0-5162b0782eb0_5.5___1242x2208__U00283_U0029__U00282_U0029.jpg/626x0w.jpg"
],
"video_urls": []
},
"categories": [
"CPE",
"iPad",
"iPhone"
],
"click_url": "https://bitlabs.link/vc/naeXr2c/offers/1453636?source_type=offer_api&s1=",
"country_stats": [
{
"country_code": "US",
"desktop_rank": 3,
"mobile_rank": 1
}
],
"description": "Path Crypto aims to give you a simpler, smarter way to invest in digital assets.",
"device_targeting": {
"browsers": [],
"devices": [],
"operating_systems": [
{
"min_version": "12",
"name": "ios"
}
],
"platforms": [
{
"name": "smartphone"
},
{
"name": "tablet"
}
]
},
"epc": "16.34",
"events": [
{
"id": "64808a7a-6a42-11ef-8883-069eb31df495",
"is_cpc": false,
"multiple_conversions_allowed": false,
"name": "Install",
"payout": "0",
"payout_type": "flat",
"points": "0",
"translations": {},
"type_id": 0
},
{
"id": "6480b2c0-6a42-11ef-8b93-069eb31df495",
"is_cpc": false,
"multiple_conversions_allowed": false,
"name": "First Time Deposit",
"payout": "125",
"payout_type": "flat",
"points": "200000",
"translations": {},
"type_id": 0
}
],
"geo_targeting": {
"cities": [],
"countries": [
{
"country_code": "US"
}
],
"postal_codes": [],
"states": []
},
"icon": "https://main-p.agmcdn.com/offers/1453636-XyIivVW8.jpg",
"id": 1453636,
"is_game": false,
"name": "Path Crypto iOS (US) (Incentive)",
"pending_time": 10080,
"preview_url": "https://apps.apple.com/us/app/path-crypto-responsibly/id6449375736",
"requirements": "Open an account and make your first deposit to earn! New users only. You must click “Allow” if tracking permission is requested within the app. Confirms Instantly",
"support_url": "https://wall.adgaterewards.com/offer/contact/naeXr2c/1453636?s1=",
"translations": null
}
]
},
"status": "success",
"trace_id": "72b27669a61d9888"
}
Details about the response
You can find all the details about the query and response parameters of the API in the documentation page here.
Tracking link parameters
Once you get a response from the API, you will see a tracking link for each offer. Some additional information needs to be provided in these links. The s1 parameter should include the ID of the user accessing the offer. The ID can be any string up to 255 characters long. The s4 parameter can include custom subparameters you want to receive in callbacks. Learn more about it here.
All other s parameters are used internally and should not be overwritten.
Common Practices
Here are some common practices we recommend to our partners when using the static offer API.
Fetching offers
To have an updated inventory of our offers, we recommend fetching the offer list every 10 to 15 minutes. There is no indicator of which offer changed or which offer disappeared. Because of this, it is advised to compare the newly fetched list with the current one and then change offer descriptions, events, and other data or take offers offline, if they do not appear in the new list.
Storing clicks
When using the static API, it is important to note that you have to store the clicks a user has done and the events they have completed. This is important because of two reasons:
- When an offer changes (details, events, ...) the user should still see all the details at the time of the click. Otherwise, it can be irritating for the user, if they see new events all of a sudden.
- You have to store the events that the user has completed, otherwise they will not know what the progress is. You will receive the completed events via the callbacks.
For games, once a click is stored, it is advised to no longer expose the tracking link to the user and instead use a direct link to the Google Play Store or Apple App Store.
Generating a support URL
The API returns a support URL for each offer when fetching the offer list. You are free to use this, but two things have to be noted:
- You have to attach the user ID in the s1 parameter of the URL
- The supported URL will only work once a click is recognized by us. Therefore you can add a logic to show the URL only once a user has clicked on the offer. A click for games means that the user saw the Google Play or the App Store page.
How do I filter the response to only see games?
The API does currently not support a query parameter to filter for games. However, we added a parameter called is_game. If this parameter is true, then the offer is a gaming offer.
How do I filter the response by country?
The API does currently not support a query parameter to filter the response by country. However, we added a parameter in the response called country_stats which contains a country code.
How do I filter the response by device?
You can find the device_targeting field in the response for each offer. This will include information about the operating system of an offer, for exampleios or android. The offer is available for all devices if no information is provided in the device_targeting field.
Updated about 2 months ago