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.

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
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

...

Expand

title	Native Creative Response Example

Code Block

{
    "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

Note

Status

colour	Yellow
title	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

Status

colour	Yellow
title	권장

String

Android IMEI

Note
udid is not collectible since the release of Android 10

android_id

Status

colour	Yellow
title	권장

String

Android ID

udid_sha1

Status

colour	Yellow
title	권장

String

SHA1-applied Android IMEI

Note
udid is not collectible since the release of Android 10

android_id_sha1

Status

colour	Yellow
title	권장

String

SHA1-applied Android ID

sub_publisher_id

Status

title	선택

String

Sub-publisher’s unit ID

sub_publisher_user_id

Status

title	선택

String

Sub-publisher app’s user Id

device_name

Status

colour	Yellow
title	권장

String

Device model name

carrier

Status

colour	Yellow
title	권장

String

Mobile carrier

google_account_sha1

Status

colour	Yellow
title	권장

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

Status

title	선택

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

Status

title	선택

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

Status

title	선택

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.

...

Versions Compared

Old Version 1

New Version 2

Key

1. Ad List Request

Response Fields

Details for `ads` Fields:

Details for `creative` Fields:

2. Ad Participation Request

4) HTTP Request parameters

5) Response

3. Reward Request Postback API

Page Comparison

Versions Compared

Old Version 1

New Version 2

Key

1. Ad List Request

Response Fields

Details for ads Fields:

Details for creative Fields:

2. Ad Participation Request

4) HTTP Request parameters

5) Response

3. Reward Request Postback API

Details for `ads` Fields:

Details for `creative` Fields: