Campaigns API

Create, update, pause and delete campaigns, block sources, manage source lists, creatives and conversion tracking through the advertiser API.

All advertiser endpoints sit under /advertiser and need an account with the advertiser role. Paths below are relative to https://ulumob.com/api/v1. See Authentication and keys for the header to send.

Campaign endpoints

Method and path	What it does
`GET /advertiser/campaigns`	Paginated list, newest first. Filters: `status` (`moderation`, `active`, `paused`, `rejected`, `completed`), `format`, `per_page` (up to 100, default 25).
`POST /advertiser/campaigns`	Creates a campaign. It starts in `moderation`. Returns 201.
`GET /advertiser/campaigns/{id}`	One campaign with its targeting and ads.
`PUT /advertiser/campaigns/{id}`	Replaces the campaign settings and ads.
`POST /advertiser/campaigns/{id}/toggle`	Switches an approved campaign between `active` and `paused`.
`DELETE /advertiser/campaigns/{id}`	Deletes the campaign. It stops serving at once; its report history stays.
`POST /advertiser/campaigns/{id}/block`	Stops buying one zone or sub-ID.

Campaign payload

{
  "name": "Pop US mobile",
  "format": "popunder",
  "pricing_model": "cpm",
  "bid_amount": 1.5,
  "daily_budget": 50,
  "total_budget": 1000,
  "frequency_cap": {"count": 1, "unit": "impressions", "period_minutes": 1440},
  "targeting": {
    "geos": {"mode": "include", "values": ["US", "CA"]},
    "devices": {"mode": "include", "values": ["mobile"]},
    "blacklist_zones": [123]
  },
  "ads": [
    {"destination_url": "https://tracker.example/c?cid={click_id}&z={zone_id}", "weight": 100}
  ]
}

Main rules:

Format and pricing. Each format allows certain pricing models; for example popunder takes cpm or cpa, push takes cpc or cpa, video takes cpm or cpv. Neither can change after creation.
Bid. bid_amount must meet the floor for the targeted countries.
Daily budget. At least 15, or 50 for video.
Zone bids. zone_bids is a list of {"zone_id": 123, "bid": 0.45}: the bid used in that zone instead of bid_amount. Each zone must be active and of the campaign format, and each bid must meet the floor. Up to 50 zones. On PUT, sending zone_bids replaces the list (an empty list clears it) and leaving it out keeps it; GET returns it.
Budget alert. notify_on_budget (true or false) sends one email the first time the daily budget is spent each day, in your account time zone.
Completed. A campaign becomes completed when its end date passes or its total budget is spent. A completed campaign cannot be resumed with toggle; extend ends_at or total_budget with PUT and it returns to active.
Ads. 1 to 50 per campaign. The fields each format needs are listed in Creative specs. Images and icons are referenced by creative_id and icon_creative_id from your media library.
Targeting. Each dimension is null (any) or {"mode": "include" | "exclude", "values": [...]}. Dimensions include geos, regions, cities, devices, os, browsers, browser_languages, site_languages, categories, site_types, domains and subids. Zone lists are plain arrays: whitelist_zones and blacklist_zones.

On PUT, sending targeting replaces it and leaving it out keeps it. Ads missing from the ads list are removed; include an existing ad's id to keep it. New or edited ads go back to moderation.

A validation failure returns 422 with an errors object keyed by field, for example ads.0.creative_id.

Blocking a source

POST /advertiser/campaigns/{id}/block
{"zone_id": 123}

or {"subid": "partner-a"}. Send one, not both. A blocked zone joins blacklist_zones; a sub-ID joins the exclude list, or leaves the include list if the campaign uses one. The response is the updated targeting. The campaign does not go back to review. See Blocking sources.

Source lists

Reusable lists you attach to several campaigns:

Method and path	What it does
`GET /advertiser/filters`	Your lists with their items and attached `campaign_ids`.
`POST /advertiser/filters`	`{name, type, items, campaign_ids?}`
`PUT /advertiser/filters/{id}`	Changes `name`, `items` and, if sent, `campaign_ids`. The type is fixed.
`DELETE /advertiser/filters/{id}`	Deletes the list and detaches it everywhere.

type is one of zone_include, zone_exclude, domain_include, domain_exclude, subid_include, subid_exclude, isp_exclude, ip_allow or ip_block. A list holds 1 to 10,000 items.

Creatives

Method and path	What it does
`GET /advertiser/creatives`	Filters: `kind`, `folder`, `per_page`.
`POST /advertiser/creatives`	Multipart: `kind` (`image`, `icon`, `video`), `file`, `folder?`.
`GET /advertiser/creatives/folders`	Folder names in use.
`DELETE /advertiser/creatives/{id}`	Refused with 422 while an ad uses it.

Limits are listed in Media library.

Conversion tracking

Method and path	What it does
`GET /advertiser/tracking`	Your postback URL templates, postback secret and conversion types.
`PUT /advertiser/tracking/conversion-types`	`{"conversion_types": [{"letter": "A", "name": "Sale", "is_active": true, "allow_repeats": false}]}`
`POST /advertiser/tracking/rotate-secret`	Issues a new postback secret. Postbacks signed with the old one stop validating at once.
`GET /advertiser/tracking/rejected`	Up to 100 refused postbacks from the last 7 days, with the reason.

See Postback setup for signing postbacks.

Billing

GET /advertiser/billing/transactions returns your balance and transactions. POST /advertiser/billing/stripe-deposit starts a card deposit; see Deposits and receipts.

Something missing or wrong? Tell us.