Publisher API

Add and verify websites, create zones and fetch their codes, check zone quality, read earnings and request payouts through the API.

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

Websites

Method and path	What it does
`GET /publisher/websites`	Your sites with a zone count. `per_page` up to 100, default 25.
`POST /publisher/websites`	Adds a site. Returns 201 with verification instructions.
`GET /publisher/websites/{id}`	One site with its zones and verification instructions.
`PUT /publisher/websites/{id}`	Updates details. The domain cannot change.
`DELETE /publisher/websites/{id}`	Removes the site and archives its zones.
`POST /publisher/websites/{id}/verify`	Checks the verification code. Up to 6 calls a minute.

Creating a site:

{
  "name": "Example blog",
  "url": "https://example.com",
  "verification_method": "meta_tag",
  "categories": ["technology"],
  "languages": ["en"]
}

verification_method is meta_tag, file_upload or dns_txt. The response has a verification object that says where to put the code (place) and what to put there (value). description and website_type are optional.

PUT accepts name, description, category, categories, blocked_ad_categories, languages and website_type. Categories are slugs from GET /categories; blocked_ad_categories are the ad categories that never serve on the site (sensitive ones are blocked on a new site). Editing a rejected site sends it back to review.

POST /publisher/websites/{id}/ads-txt looks for our line in the site's ads.txt and returns {line, ok, checked_at, required}; the same object is in every site response under ads_txt.

verify returns the site with verified_at set when the code is found, or 422 with the instructions again when it is not. Verification is followed by a manual review before zones serve. See Add a website.

Zones

Method and path	What it does
`GET /publisher/zones`	Your zones, 50 per page. Filter with `website_id`; archived zones only with `archived=1`.
`POST /publisher/zones`	Creates a zone. Returns 201 with its codes under `tag`.
`PUT /publisher/zones/{id}`	Updates a zone.
`DELETE /publisher/zones/{id}`	Deletes a zone that never served; archives one that did. Returns `{"status": "deleted"}` or `{"status": "archived"}`.
`GET /publisher/zones/{id}/tag`	The zone's codes.
`GET /publisher/zones/quality`	Last 7 days per zone: impressions, clicks, conversions, flagged events, earnings, CTR and flagged share.

Creating a zone:

{
  "website_id": 77,
  "name": "Header banner",
  "format": "banner",
  "banner_size": "728x90",
  "reserve_cpm": 0.5
}

format is one of popunder, push, in_page_push, native, banner, interstitial, redirect, video or telegram.
banner_size is required for banners and not allowed for other formats: 300x250, 728x90, 320x50 or 160x600.
reserve_cpm is the lowest CPM you accept, in USD, from 0 to 100.
anti_adblock is a boolean.
fallback_url is an optional http or https address shown in the zone when no campaign fills it (up to 2,048 characters; null removes it).
settings can hold allow_animation (false keeps animated GIFs out), allow_iframes (false: the banner code renders in the page), display_type (inline or floater, native / in-page push / Telegram), pop_frequency ({"count": 2, "hours": 24}, popunder and redirect only) and blocked_ad_categories (category slugs). A PUT changes only the settings it sends.

On PUT, website_id, format and banner_size cannot be sent. You can change name, reserve_cpm, anti_adblock, fallback_url, settings and status (active, paused or archived). An archived zone cannot be changed.

The tag response always has script, plus one of:

Key	Formats
`direct_url`	`popunder`, `redirect`
`iframe`	`banner`
`vast_url`	`video`
`json_url`	All other formats

See Zone codes for how to use each one.

Reports

GET /publisher/reports takes the same parameters as the advertiser report, without campaign_id and ad_id, and returns earnings. See Reports API.

Earnings and payouts

Method and path	What it does
`GET /publisher/earnings`	`earnings_balance` (available), `hold_balance` (requested, unpaid), `min_payout` and paginated `transactions`.
`GET /publisher/payout-methods`	Your methods, details masked.
`POST /publisher/payout-methods`	Adds a method; send your account `password`, and a two-step `code` when that is on. It is confirmed by the link we email to the account and can be paid 48 hours later.
`PUT /publisher/payout-methods/{id}`	Changes `label` and/or `details`; new details need the `password` (and `code`) and a new confirmation.
`DELETE /publisher/payout-methods/{id}`	Removes a method no payout is on its way to.
`POST /publisher/payout-methods/{id}/default`	Makes it the default.
`POST /publisher/payout-methods/{id}/confirm`	Emails the confirmation link again.
`POST /publisher/payouts/request`	Requests a payout. Body: `{"amount": 150}`, or empty for everything available.

Adding a method:

{"method": "usdt_trc20", "details": {"address": "T..."}, "is_default": true}

`method`	`details` fields
`usdt_trc20`, `bitcoin`	`address`
`paypal`, `payoneer`	`email`
`capitalist`	`account`
`wire`	`account_name`, `iban`, `bic`, `country`

A payout request returns 201 with the pending transaction, or 422 when there is no default method, the amount is below the minimum or above what is available, or the last request is less than 7 days old. See Payouts.

Something missing or wrong? Tell us.