Connecting Buzzvil on Clarisights

Buzzvil is an AI-powered full-funnel mobile advertising platform popular in Korea and APAC. Connecting Buzzvil to Clarisights lets you blend Buzzvil spend, impressions, clicks, and conversion performance with your other paid channels and analyze it side-by-side with attribution data.

At a glance

Authentication	API Token (Buzzvil-issued, sent as Authorization: Token <token>)
Permissions needed	An API token with read access to ad.buzzvil.com/api/public — specifically the adgroups, lineitems, and creative_sets endpoints and their per-object /report sub-endpoints
Account discovery	Single account per token — one Clarisights account is created per Buzzvil API token / login
Data freshness	Daily (Airflow DAG with a 7-day look-back window)
Lookback window	7 days on every scheduled run; up to 100 days per request when backfilling
Backfill on connect	Last 7 days; longer windows available on request
Timezone	UTC (Etc/UTC)
Currency	Account currency preserved on ingest as Cost (Local Currency); Cost is converted to your reporting currency by Clarisights
Levels supported	Account · Campaign · Ad Group · Ad
Limited rollout	No

Prerequisites

• An active Buzzvil advertiser account

• An API token issued by Buzzvil — request from your Buzzvil account manager

• Token must have read access to the public adgroups, lineitems, and creative_sets endpoints

• Each token must be unique — the same token cannot be connected twice in the same Clarisights workspace

Steps to Connect

Step 1 — Obtain your API token

Contact your Buzzvil account manager to issue an API token for your advertiser. Copy the full token value — you will paste it into Clarisights in Step 3.

Treat your API token like a password. It grants read access to all campaigns, ad groups, and creatives owned by the linked Buzzvil account.

Step 2 — Add Buzzvil in Clarisights

In Clarisights, go to Integrations → Buzzvil → Add Account.

[TODO: Screenshot needed — Integrations page Buzzvil row with Add Account button]

Step 3 — Enter credentials

Provide a friendly Account Name (this becomes the Clarisights account name) and paste your API Token. Click Validate.

Clarisights authenticates by listing ad groups (GET /api/public/adgroups) to confirm the token works, then creates a single account using your account name as the label.

⚠ "Token already in use" → The same Buzzvil API token is already connected on another user record in this workspace. Use a different token, or remove the existing connection first.

⚠ "Invalid token. Please check your authentication credentials and try again." → Buzzvil rejected the token. Confirm the token has not been rotated or revoked in the Buzzvil portal. Re-issue a token from your Buzzvil account manager and retry.

Step 4 — Confirm the account

Buzzvil creates exactly one Clarisights account per token, using the Account Name you supplied. There is no multi-account selector — if you manage multiple Buzzvil advertisers under separate logins, repeat Steps 2-3 with each token.

Verify the connection

• Go to Integrations → Buzzvil. The connected account should show a "Connected" status.

• First data appears within ~24 hours of the next scheduled pull (Buzzvil DAG runs daily on Airflow with a 7-day look-back).

• Quick start: create a new report, add Buzzvil as the data source, and add Account · Campaign · Ad Group · Impressions · Clicks · Cost.

Data available

Hierarchy

Buzzvil's native naming differs from the Clarisights standard. Each native level shifts down by one in Clarisights so the standard four-level hierarchy is preserved:

Native level (Buzzvil)	Clarisights level
Ad Group	Campaign
Line Item	Ad Group
Creative Set	Ad

This mapping is implemented in BuzzvilInputSource::LEVEL_MAP: report metrics are fetched at the Creative Set level and rolled up to Line Item and Ad Group by Clarisights, so Campaign / Ad Group / Ad totals all reconcile.

Dimensions

Dimension	Level	Description
Account	Account	Account name supplied during connection
Campaign / Campaign ID	Campaign	Buzzvil Ad Group name and ID, surfaced as Campaign in Clarisights
Campaign Currency	Campaign	Currency of the Buzzvil ad group
Ad Group / Ad Group ID	Ad Group	Buzzvil Line Item name and ID, surfaced as Ad Group in Clarisights
Ad Group Type	Ad Group	Line Item type
Ad Group Start Date / End Date	Ad Group	Flight dates of the Line Item
Ad Group Platform	Ad Group	Target platform (iOS/Android/Web)
Ad Group Country	Ad Group	Target country
Ad Group Revenue Type	Ad Group	Revenue model (CPC, CPM, CPI, etc.)
Ad Group Objective	Ad Group	Campaign objective
Ad Group Active	Ad Group	Whether the Line Item is active
Ad Group Unit Price	Ad Group	Configured unit price (CPC/CPM/CPI bid)
Ad Group Currency	Ad Group	Currency of the Line Item; also drives the per-row currency for cost conversion
Ad Group Budget	Ad Group	Configured Line Item budget
Ad / Ad ID	Ad	Buzzvil Creative Set name and ID, surfaced as Ad in Clarisights

Metrics

Metric	Description
Impression	Total impressions
Click	Total clicks
Conversion	Total conversion events
Cost	Total cost converted to your Clarisights reporting currency
Cost (Local Currency)	Total cost in the Buzzvil ad group's native currency, preserved as-is

Limitations & known constraints

• One account per token: Buzzvil's API does not expose a multi-account endpoint. Each token connects exactly one Clarisights account, named after the Account Name you supplied. Multi-advertiser companies must onboard each Buzzvil login separately.

• Tokens must be unique: re-using the same token across two Clarisights user records in the same workspace is rejected ("Token already in use").

• Naming differs from Clarisights standard: Buzzvil's Ad Group, Line Item, and Creative Set are remapped to Campaign, Ad Group, and Ad respectively. Reports authored against generic Campaign / Ad Group / Ad levels work out of the box, but raw API field names will not match.

• Per-object report fan-out: reports are fetched per Creative Set, then rolled up. Accounts with very large numbers of creative sets can take longer to backfill.

• Limited segment breakdowns: the public Buzzvil API exposes Line Item-level platform and country, but does not return per-impression demographic, device, or placement breakdowns.

• Sparse public docs: Buzzvil's API documentation is not publicly indexed. Schema changes typically require a coordinated update with the Clarisights integrations team.

Operating notes

• Refresh schedule: daily, via the Airflow buzzvil DAG (rake task ingestion:custom_advertising:fetch_and_process).

• Lookback: 7 days (today_7d) on every run, so late-arriving conversions and corrections within the last week are picked up automatically.

• Concurrency: reports for up to 10 creative sets are fetched in parallel; pagination on list endpoints is handled automatically.

• Currency conversion: each row carries the Buzzvil Ad Group's native currency. Clarisights converts Cost to your reporting currency and preserves Cost (Local Currency) for reconciliation against the Buzzvil portal.

• Credential rotation: update the API token any time from Integrations → Buzzvil → Edit API Token.

Need help?

When contacting support from the in-app messenger, please include:

• The integration name and account ID (Integrations → Buzzvil)

• The exact error message or screenshot

• The step where the issue occurred

• When the issue started