Buzzvil’s Publisher Offerwall S2S API allows you to directly request Buzzvil servers for ads. It is designed to use standard HTTP protocols and return JSON payloads in response to the HTTP requests.

There are largely three parts to the Offerwall API integration:

Ad List Request
1. Once you request ads, Buzzvil will respond with a list of ads along with a variety of information that each ad contains. Some of this information includes ad IDs, titles, descriptions, platforms, age, sex… and the list goes on. You can use this information to create the Offerwall UI, as well as for targeted allocation of ads.
Ad Participation Request
1. When a user clicks an ad, call the Ad Participation Request API to confirm eligibility for participation.
Reward Request Postback
1. When a user performs all the instructed actions for an ad, Buzzvil will request your server to reward the user.

1. Ad List Request

Objective: Call the Ad List Request API to retrieve a list of Ads.

	Category	Description
1	Request Direction	Publisher → Buzzvil
2	HTTP Request method	GET
3	HTTP Request URL	https://ad.buzzvil.com/api/v1/list
4	HTTP Request parameters	Field Description `unit_id` (Integer) : Identifier for the publisher
5	Response	Returned in JSON format Refer to the below “Response Fields” for field details

Response Fields

Field	Type	Description
`ads`	list	List of ads Detailed fields can be found in the '`ads` Fields' table
`code`	String	Processing result code only `200` indicates success
`msg`	String	Processing result message

Details for `ads` Fields:

Field	Type	Description
`id`	Integer	Ad ID (identifier)
`title`	String	Ad title
`description`	String	Ad description
`action_description`	String	Description of the action required to participate in the ad
`icon`	String	Icon image address
`revenue`	String	Publisher rate
`revenue_type`	String	Type of ad. Consider additional types in the future. `cpi`: App install `cpe`: App launch or post-launch action `cpa`: Action `cpl`: Facebook Like `cpinsta`: Instagram Follow `cps`: Shopping `cpyoutube`: YouTube Ad `cpq`: Quiz `cpk`: KakaoTalk channel subscription `cpylike`: YouTube Subscribe + Like `cptiktok`: TikTok Follow `cpnstore` : Naver SmartStore Like `cpqlite` : Quiz `cpcquiz` : Quiz with contents i.e. `"cpi"`
`package_name`	String	Android `package_name`
`url_scheme`	String	iPhone URL scheme
`platform`	String	Supported platforms `A`: Android `I`: iPhone `W`: Both platforms Note: Platform parameters are set by ad operators at Buzzvil. If you manually change this value of an ad, it may not target the intended users.
`age_from`	Integer	Used to target users from a specified age. When no `age_from` targeting: `null`
`age_to`	Integer	Used to target users to a specified age. When no `age_to` targeting: `null`
`age_ranges`	JSON	Used to target multiple ranges of age. If using the `age_ranges` parameter, `age_from` and `age_to` values can be ignored. When there is `age_ranges` targeting: `[{"from":10, "to":20}, {"from":30, "to":40}]` When no `age_ranges` targeting: `[]`
`sex`	String	Used to target sex. `M`: Male `F`: Female When there is no sex targeting: `null`
`relationship`	String	Used to target marital status. `S`: Single `M`: Married When there is no `relationship` targeting: `null`
`carrier`	String	Used to target mobile carrier. `kt`: KT `skt`: SKT `lgt`: LGT When there is no `carrier` targeting: `null`
`udid_required`	Bool	When `udid` value is required for Ad Participation Request and Conversion APIs `true` When `udid` value is not required for Ad Participation Request and Conversion APIs `false`
`device_name`	String	Used to target device models. Each device model is separated by a comma. ex) `SHV-E250S,SHV-E275K,SM-G928L` `SHV-E250S` OR `SHV-E275K` OR `SM-G928L` device model is targeted.
`target_app`	String	Used to target users with specific Android apps Each app is separated by a comma. To not target specific apps, add a dash ( - ) in front of the package names. ex) `Pl.idreams.skyforcehd,com.imangi.templerun2` `Pl.idreams.skyforcehd` OR `com.imangi.templerun2` app is targeted ex) `com.thinkreals.couponmoa,-com.supercell.clashofclans` Target users who installed the `com.thinkreals.couponmoa` app or don’t target users with the `com.supercell.clashofclans` app
`region`	String	Used to target regions. Each region is separated by a comma. Can target 도/시 ex) `서울특별시 강남구,경상남도` `서울특별시 강남구` OR `경상남도` users are targeted.
`creative`	list	List of creatives Detailed fields can be found in the '`creative` Fields' table.

Details for `creative` Fields:

Field	Type	Description
`ID`	Integer	Creative ID
`short_action_description`	String	A brief description of the action required to participate in the ad
`height`	integer	627 for native creative, 0 otherwise
`width`	integer	1200 for native creative, 0 otherwise
`action_description`	String	A description of the action required to participate in the ad (22 letters recomended; 44 letters max)
`call_to_action`	String	Call to action e.g., "Click to Follow"
`image_url`	String	URL of the image file for native creative
`icon`	String	Icon image visible in the offerwall list

Note: You can only request for Ads that are set with native creatives when requesting the Ad list. Include the following key and value in the request parameters:

Key: types
Value: {"NATIVE":[]}

Native Creative Response Example

{
    "ads": [
       {
            "id": 1234757, //camapign_id를 의미합니다. 이해를 돕기 위한 임의의 숫자입니다.
            "icon": "https://oooooooooo.cloudfront.net/uploads/1671688583-ZRSHX.png",
            "reward_name": "P",
            "url_scheme": "",
            "package_name": "",
            "target_app": "",
            "action_description": "[참여방법]\n- oooo을 완료하시면 포인트가 지급됩니다.(최초 계좌개설에 한함)\n\n[주의사항]\n- 이미 참여한 이력이 있다면 포인트가 지급되지 않습니다.\n- WIFI가 아닌 환경에서는 데이터 이용료가 발생할 수 있습니다.",
            "description": "캠페인에 참여하세요.",
            "revenue_type": "cpa",
            "image": "",
            "creative": {
                "id": 1170669,
                "creative_type": 1,
                "category": "finance",
                "width": 1080,
                "height": 2340,
                "image_url": "https://ooooooooooo.cloudfront.net/uploads/1675213124-FUZZW_processed.jpg",
                "click_url": "https://ooooooooo.ap1.adtouch.dfinery.io/api/v1/click/nfOTxG3RmEOfUdurAoHShw?m_adid={ifa}&cb_1={cb_param1}&adv_campaign=direct&adv_ad=benefit_50000&adv_adgroup=app_none&adv_agency=money_pocket&adv_creative=make_ing&adv_keyword=direct_display_buzzvill_app_none_benefit_50000_money_pocket_make_ing&adv_placement=display&utm_source=buzzvill&utm_medium=display&utm_campaign=direct&utm_term=display_ad&utm_content=direct_display_buzzvill_app_none_benefit_50000_money_pocket_make_ing",
                "is_deeplink": true,
                "adchoice_url": "",
                "icon": "https://ooooooooooooo.cloudfront.net/uploads/1671688583-ZRSHX.png",
                "background_image_url": "",
                "html": "",
                "description": "캠페인에 참여하세요.",
                "action_description": "[참여방법]\n- ㅇㅇㅇㅇ을 완료하시면 포인트가 지급됩니다.(최초 계좌개설에 한함)\n\n[주의사항]\n- 이미 참여한 이력이 있다면 포인트가 지급되지 않습니다.\n- WIFI가 아닌 환경에서는 데이터 이용료가 발생할 수 있습니다.",
                "call_to_action": "ooooo하기",
                "short_action_description": "캠페인에 참여하세요.",
                "layout_type": 16,
                "landing_type": null,
                "name": "oooo EVENT"
            },
            "platform": "W",
            "age_to": null,
            "age_from": null,
            "age_ranges": [],
            "sex": null,
            "carrier": "",
            "relationship": null,
            "device_name": "",
            "region": "",
            "udid_required": false,
            "title": "계좌개설 EVENT",
            "revenue": 8500.0
        },
        ...
    ],
    "code": 200,
    "msg": "allocate successfully"
}

2. Ad Participation Request

Objective: To participate in an ad, the ad participation request API must be called to confirm eligibility.

	Category	Description
1	Request Direction	Publisher → Buzzvil
2	HTTP Request method	POST
3	HTTP Request URL	https://ad.buzzvil.com/api/v1/participate
4	HTTP Request parameters	Refer to the ‘4) HTTP Request parameters’ table for field descriptions RECOMMENDED It is recommended to provide parameters if possible, as omitting parameters may result in stricter abuser screening.
5	Response	Returned in JSON format Refer to the below “Response Fields” for field details

4) HTTP Request parameters

Field	Type	Description
`unit_id`	Integer	Publisher Unit ID
`campaign_id`	Integer	Ad ID
`ifa`	String	Android: Advertising ID(GAID) iOS: Identifier for Advertiser(IDFA)
`custom`	String	Publisher app’s User ID
`client_ip`	String	IP address of the user who participated in the ad ex) 123.123.123.123
`udid` 권장	String	Android IMEI udid is not collectible since the release of Android 10
`android_id` 권장	String	Android ID
`udid_sha1` 권장	String	SHA1-applied Android IMEI udid is not collectible since the release of Android 10
`android_id_sha1` 권장	String	SHA1-applied Android ID
`sub_publisher_id` 선택	String	Sub-publisher’s unit ID
`sub_publisher_user_id` 선택	String	Sub-publisher app’s user Id
`device_name` 권장	String	Device model name
`carrier` 권장	String	Mobile carrier
`google_account_sha1` 권장	String	SHA1-applied Google account on the Android device Only the first account is transmitted for multiple accounts Can be retrieved by using the `getAccountsByType(`"`com.google`"`)` function. Refer to 3) “How to Retrieve Google Accounts”
`custom2` 선택	String	Custom value specified by the publisher value transmitted to the publisher by Buzzvil when making a postback request Max length is 255 `custom2~4` can be transmitted
`custom3` 선택	String	Custom value specified by the publisher value transmitted to the publisher by Buzzvil when making a postback request Max length is 255 `custom2~4` can be transmitted
`custom4` 선택	String	Custom value specified by the publisher value transmitted to the publisher by Buzzvil when making a postback request Max length is 255 `custom2~4` can be transmitted

5) Response

Field

Type

Description

code

Integer

Processing result code

Participation is only allowed when the code is 200

msg

String

Processing result message

landing_url

String

Landing URL of the advertiser's page

3. Reward Request Postback API

This is a request sent from Buzzvil to the publisher server when a user performs the desired actions of the participating ad.

Please note that Buzzvil does not directly reward the users

Please refer to the Reward Request Postback API Integration Guide. Once done with the integration, kindly provide the endpoint URL to the Buzzvil manager.

[ENG] Publisher Offerwall S2S API Integration Guide