Version: v2

Placement and ad-slot endpoints

These routes use a publisher dashboard Authorization: Bearer SESSION_TOKEN and the /publisher/v2 base path. The token belongs to a PUBLISHER, ADMIN, or SUPERADMIN account. A static feed key or SDK session token does not grant access. Use the placement guide for the console workflow.

Placements

Method	Path	Response	Purpose
GET	`/placements?search=&status=`	`200 {items,count}`	List owned non-archived placements
POST	`/placements`	`201` placement	Create a draft
GET	`/placements/{placementId}`	`200` placement with `adSlots`	Read owned placement
PATCH	`/placements/{placementId}`	`200` placement	Update editable fields
POST	`/placements/{placementId}/request-review`	`200` placement	Move a draft or rejected placement to review
DELETE	`/placements/{placementId}`	`204`	Archive only when no live or historical obligations exist

POST /placements accepts type (ANDROID_APP, IOS_APP, WEBSITE, API_NETWORK), name, platformIdentity, and optional storeUrl, minimumSdkVersion, recommendedSdkVersion, and requireConsent. Android and iOS require a public HTTPS store URL. The server normalizes the identity and defaults the minimum SDK version to 2.0.0 when none is supplied.

GET /placements supports search (name, exact placement ID, or identity) and status; it returns non-archived placements in newest-first order. GET /placements/{placementId} additionally returns its non-archived adSlots. A create response includes placementId, type, normalized identity, status: "DRAFT", platform, privacy settings, capabilities, minimum/recommended SDK versions, released, and safe callback configuration. No callback secret is returned by a placement read. Use the generated placementId unchanged in SDK sessions and slot calls.

POST /publisher/v2/placements
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json

{
  "type": "ANDROID_APP",
  "name": "Puzzle Quest — Android",
  "platformIdentity": "com.example.puzzlequest",
  "storeUrl": "https://play.google.com/store/apps/details?id=com.example.puzzlequest",
  "minimumSdkVersion": "2.0.0",
  "requireConsent": true
}

PATCH accepts name, store URL, SDK version requirements, and consent setting. It does not change the placement type or identity. Only an administrator can call /placements/{placementId}/review; publishers request review and wait for an authorized decision.

POST /placements/{placementId}/request-review accepts an empty JSON body and moves only a DRAFT or REJECTED placement to PENDING_REVIEW. Administrator review may produce VERIFIED or REJECTED; a verified identity still requires a ready slot and production release. DELETE /placements/{placementId} returns 204 and archives only a placement with no release, active/disabled slot, historical SDK session, or configured callback obligation. It does not erase history.

Ad slots

Method	Path	Response	Purpose
POST	`/placements/{placementId}/ad-slots`	`201` slot	Create a slot
PATCH	`/placements/{placementId}/ad-slots/{adSlotId}`	`200` slot	Create a new configuration revision
POST	`/placements/{placementId}/ad-slots/{adSlotId}/reward-preview`	`200` preview	Convert sample `usdMicros` to virtual currency
GET	`/placements/{placementId}/ad-slots/{adSlotId}/snippets`	`200` snippets	Get credential-free SDK snippets

For offers, slot type is OFFERWALL, OFFER_API, or STATIC_API, subject to placement type. POST accepts name, optional currency, design, exposure, policy, and offerDelivery. The currency object can set name, decimals, rateNumeratorMinorUnits, rateDenominatorUsdMicros, minimumPayoutMinorUnits, and rounding (DOWN, NEAREST, UP). A zero conversion numerator leaves the slot unready.

The policy object accepts allowedCountries, blockedCountries, blockedCampaignIds, excludedCampaignTaskTypes, and excludedCampaignCategories. offerDelivery.sort accepts PAYOUT, CONVERSION_RATE, EPC, or ECPM; minimumPayoutMicros is a nonnegative integer. PATCH retains unspecified settings, increments configurationVersion, and creates an immutable revision. Slot type cannot be changed by patching.

POST /publisher/v2/placements/PLACEMENT_ID/ad-slots
Authorization: Bearer SESSION_TOKEN
Content-Type: application/json

{
  "name": "Main rewards tab",
  "type": "OFFER_API",
  "currency": {"name": "Coins", "rateNumeratorMinorUnits": 100},
  "policy": {"allowedCountries": ["US"], "excludedCampaignTaskTypes": ["GAMBLING"]},
  "offerDelivery": {"sort": "ECPM", "minimumPayoutMicros": 0}
}

Inspect readiness.ready and readiness.reasons in the response. A slot can be ready while production delivery remains unreleased. For exact user steps see offer ad slots.

POST /placements/{placementId}/ad-slots/{adSlotId}/reward-preview takes {"usdMicros":750000} and returns usdMicros, minorUnits, currency, and decimals using that slot's rate and rounding. Use it to compare the displayed virtual reward with the intended publisher payout. GET /placements/{placementId}/ad-slots/{adSlotId}/snippets returns the placement and slot IDs, credential-free android, ios, and web initialization snippets, and containsCredential: false. Those snippets carry identifiers only; they do not create a session or bypass identity and consent checks.

PATCH merges named slot sections, increments configurationVersion, and stores an immutable configuration revision. Type is immutable. A non-active slot becomes READY when its verified placement, capability, and positive currency rate meet readiness; otherwise it remains DRAFT. An ACTIVE slot retains its state on patch, but delivery still evaluates current eligibility. Keep the placement and slot IDs together in support records, and treat revision/version identifiers as audit references.

Placements​

Ad slots​

Placements

Ad slots