Advertiser API

The advertiser endpoints are prefixed with /api/advertiser. Except for login / register / password reset, all require the advertiser JWT in the request header: Authorization: Bearer <token>.

For the response envelope, pagination, and error-code conventions, see Overview & Authentication.

Authentication

Login

POST /api/advertiser/auth/login

Param	Type	Required	Description
username	string	Yes	Username; login by registered email is also supported
password	string	Yes	Login password

curl -X POST https://api.adbnk.co/api/advertiser/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"secret123"}'

{
  "code": 0,
  "message": "Login successful",
  "data": {
    "token": "eyJ0eXAiOiJKV1Qi....",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 12,
      "username": "demo",
      "nickname": "Demo",
      "email": "[email protected]",
      "advertisement_id": 8,
      "role": "ADMIN"
    }
  },
  "timestamp": 1752200000
}

Register

POST /api/advertiser/auth/register

Uses progressive KYC; the minimum required fields are just email + password. A successful registration returns a usable token directly.

Param	Type	Required	Description
email	string	Yes	Valid email, globally unique
password	string	Yes	Password, at least 8 characters
username	string	No	Auto-derived if omitted (3-30 alphanumeric/underscore)
mobile	string	No	Mobile number
company_name	string	No	Company name
contact_name	string	No	Contact person
industry	string	No	Industry name

Other auth endpoints

Method	Path	Description
POST	/auth/forgot-password	Send reset email, param email; one per 60s per email
POST	/auth/reset-password	Params token, new_password, confirm_password
POST	/auth/logout	Log out (frontend just discards the token)
GET	/auth/profile	Get the current advertiser's info
POST	/auth/password	Change password, params old_password, new_password, confirm_password

Campaigns

List

GET /api/advertiser/campaigns

Param	Type	Required	Description
page / page_size	int	No	Pagination
keyword	string	No	Fuzzy search by name
status	string	No	Status filter
pricing_model	string	No	Pricing model filter
start_date / end_date	date	No	Creation time range

Create

POST /api/advertiser/campaigns

Precondition

Creating a campaign enters the review flow and requires account profile completeness at basic, otherwise it returns 412.

Param	Type	Required	Description
name	string	Yes	Campaign name
ad_type	string	Yes*	Ad type (BANNER/NATIVE/VIDEO/POPUP/REWARDED/RESPONSIVE, etc.). Can be derived from campaign_option_id
campaign_option_id	int	No	Ad-format option ID; can replace ad_type
price / bid	number	Yes	Bid; bid falls back to price, cannot be negative
pricing_model	string	No	Pricing model, default CPC; options CPM/CPA/CPV/CPS
type	string	No	Campaign type, default PERFORMANCE
objective	string	No	Objective, default TRAFFIC
daily_budget	number	No	Daily budget, cannot be negative
total_budget	number	No	Total budget, cannot be negative
start_date / end_date	date	No	Serving start/end; empty means unlimited
landing_url	string	No	Landing page URL
tracker_id	int	No	Conversion tracker ID; required for CPA/CPS billing
rotation_mode	string	No	Rotation mode, default EVEN
target_countries	array	No	Target countries/regions
target_devices	array	No	Target devices
target_os	array	No	Target OS
target_browsers	array	No	Target browsers
target_hours / weekdays	array	No	Daypart / weekday targeting
bid_adjustments	object	No	Per-dimension bid adjustments; see below

bid_adjustments

bid_adjustments raises or lowers the base bid by a percentage per dimension. Only three dimensions are accepted — device, geo, os — each a map of value to percentage:

{
  "device": { "MOBILE": 20, "PC": -10 },
  "geo":    { "US": 15, "JP": -20 },
  "os":     { "ANDROID": -5 }
}

Keys are upper-cased on save. Percentages are clamped to [-90, 500]; 0 and unparseable entries are dropped, and an object that ends up empty is stored as null. The engine sums every dimension that matches the request and applies the total to the base bid — see Targeting & Bidding for the calculation and its edge cases.

The same field is accepted on an ad group (/api/advertiser/adgroups), where it overrides the campaign's value for ads in that group. The override is all-or-nothing: an ad group with any bid_adjustments of its own ignores the campaign's entirely; one with null inherits the campaign's. The advertiser console only writes the campaign-level value.

curl -X POST https://api.adbnk.co/api/advertiser/campaigns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale",
    "ad_type": "BANNER",
    "pricing_model": "CPC",
    "bid": 0.35,
    "daily_budget": 200,
    "landing_url": "https://shop.example.com"
  }'

Other campaign operations

Method	Path	Description
GET	/campaigns/{id}	Details
PUT	/campaigns/{id}	Update
DELETE	/campaigns/{id}	Delete
POST	/campaigns/{id}/toggle	Enable/pause
POST	/campaigns/{id}/copy	Copy
POST	/campaigns/{id}/submit-audit	Submit for review
POST	/campaigns/batch-submit-audit	Batch submit for review
GET	/campaigns/{id}/stats	Campaign stats

Ads and ad groups

Ad groups /api/advertiser/adgroups and ads /api/advertiser/ads both provide standard CRUD (index / show / store / update / destroy) plus toggle, stats, submit-audit, and similar operations, structured the same as campaigns.

Creatives and media

Creative list

GET /api/advertiser/creatives

Param	Type	Required	Description
keyword	string	No	Name search
type	string	No	Creative type
status	string	No	Status
audit_status	string	No	Review status

Create creative

POST /api/advertiser/creatives

Param	Type	Required	Description
name	string	Yes	Creative name
creative_type	string	No	Creative subtype, default image (must be in the allowed set)
type	string	No	Display type, default IMAGE
size_id / width / height	int	No	Size
image_media_id	int	No	Main image asset ID (recommended, from the media library)
image_media_id_2	int	No	Second image asset ID
video_media_id	int	No	Video asset ID
icon_media_id	int	No	Icon asset ID
html_code	string	No	HTML ad code
vast_xml / vast_url	string	No	VAST video ad
click_url	string	No	Click URL

Media referenced by media_id

When advertisers create/update creatives, the *_url fields don't accept external URLs; images/videos can only be referenced via the media library's *_media_id, from which the server resolves a usable URL.

Media library endpoints: GET /media, POST /media/upload, POST /media/ai-image, POST /media/ai-video, POST /media/ai-copy.

Upload helpers: POST /creatives/upload (image), POST /creatives/upload-video (video).

Reporting

All reports default to the last 7 days.

Method	Path	Description
GET	/statistics/report	Summary report
GET	/statistics/campaigns	By campaign
GET	/statistics/region	Geo report
GET	/statistics/hourly	Hourly report
GET	/statistics/device	Device report
GET	/statistics/export	Export

GET /api/advertiser/statistics/report params:

Param	Type	Required	Description
start_date	date	No	Start date, default 7 days ago
end_date	date	No	End date, default today
group_by	string	No	Group dimension, default date
campaign_id	int	No	Specific campaign

curl "https://api.adbnk.co/api/advertiser/statistics/region?start_date=2026-07-01&end_date=2026-07-10" \
  -H "Authorization: Bearer <token>"

Balance and top-up

Method	Path	Description
GET	/deposits/balance	Query account balance
GET	/deposits	Top-up order list
POST	/deposits	Initiate a top-up
GET	/deposits/transactions	Fund transactions
GET	/deposits/{id}	Top-up order details
POST	/deposits/{id}/cancel	Cancel order

Initiate a top-up

POST /api/advertiser/deposits

Param	Type	Required	Description
amount	number	Yes	Top-up amount, greater than 0 and not below the minimum
payment_method	string	Yes	Payment method: BANK/USDT/ALIPAY/WECHAT/OFFLINE

Precondition

Top-up requires account profile completeness at basic, otherwise it returns 412.

curl -X POST https://api.adbnk.co/api/advertiser/deposits \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500, "payment_method": "USDT"}'

Conversion trackers

For creating / managing conversion trackers, see Events & Conversion Reporting and the Conversion Tracking guide. Related endpoints live at /api/advertiser/trackers.

TIP

For more advertiser features (optimization rules, responsive ads, referral, notification binding, etc.), refer to the advertiser console.