API reference · Watchlists and webhooks

Watch brands by domain or single advertisers; we crawl them regularly and call your webhook on changes

POST/v1/watchlists

Try it with your accountOpens in your dashboard, filled in; you see the cost before it runs.

Example request

Shell
curl -X POST "https://api.adlibapi.com/v1/watchlists" \
  -H "X-API-Key: $ADLIB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["nike.com","adidas.com"],"name":"Competitors","webhook_url":"https://hooks.example.com/adlib"}'

Send your key in the X-API-Key header. Try it in the explorer.

Request body

advertisers
string[]

Single advertiser ids <platform>:<id> (find them via /v1/advertisers/resolve). Each counts as one brand against the plan's limit

archive_videos
boolean

Keep full video files for these advertisers (default true)

domains
string[]

Brand domains: we find the brand's accounts on every platform, watch them together and add new ones as they appear. Each domain counts as one brand against the plan's limit

email_alerts
boolean

Mail a digest of each crawl's changes (new, stopped, changed, removed ads) to your account's email. Accounts only, not admin keys

exclude_advertisers
string[]

Accounts of these domains to leave out, now and when new accounts are looked for

include_advertisers
string[]

Accounts to add to the brand although we are not sure they are its own (candidates of GET /v1/companies/{domain}). Needs exactly one domain

interval_hours
integer

Crawl interval in hours (default 24). Shortest per plan: Free and Starter 24, Plus and Growth 12, Pro 6, Business 1

name
string
–
webhook_url
string

Receives advertiser.changes events (new/stopped/changed ads)

Response

data.advertiser_countrequired
integer
–
data.advertisersrequired
object[]

Empty in the list endpoint; GET /v1/watchlists/{id} has the entries

active_ads_known
integer
–
advertiser_id
string
–
last_crawl_at
datetime
–
last_error
string
–
name
string
–
next_crawl_at
datetime
–
data.archive_videosrequired
boolean
–
data.brandsrequired
string[]

Brand domains on this watchlist; each counts as one brand against the plan's limit, whatever its number of accounts

data.created_atrequired
datetime
–
data.email_alertsrequired
boolean

A digest of each crawl's changes goes to the account's email

data.idrequired
string
–
data.interval_hoursrequired
integer

Crawl interval, as set with interval_hours on create

data.namerequired
string
–
data.webhook_urlrequired
string
–