Offer campaign management endpoints
These endpoints back Campaign Studio at /performance-marketing/v2. They require the signed-in advertiser's Authorization: Bearer dashboard token and advertiser role. They explain the current console contract; there is no standalone advertiser API key for offer campaign CRUD. Server integrations should use the conversion callback API and manage campaigns in the dashboard unless an account-specific integration is arranged.
| Method | Path under /performance-marketing/v2 | Result |
|---|---|---|
| GET | /providers/capabilities | Selectable tracking provider capabilities. |
| POST | /campaigns/validate-asset | Check an advertised site or app asset. |
| GET | /campaigns | Accessible campaigns as items and count. |
| POST | /campaigns | Create a DRAFT; returns 201 and the campaign. |
| GET | /campaigns/{campaignId} | Campaign, active revision, and history. |
| GET | /campaigns/{campaignId}/readiness | Blocking review/launch reasons. |
| GET | /campaigns/{campaignId}/audit | Change history as items. |
| POST | /campaigns/{campaignId}/clone | New draft; optional name in body; returns 201. |
| POST | /campaigns/{campaignId}/revisions | New immutable revision from a campaign write input; returns 201. |
| POST | /campaigns/{campaignId}/transition | Status transition, for example {"status":"IN_REVIEW"}. |
Create and revision inputs include an advertiser owner, public copy and requirements, one advertised platform and asset, HTTPS landing URL, goals with unique external IDs and gross/publisher amounts, targeting, and budget. Readiness additionally checks creative validation, tracking, and funding. Use Campaign Studio as the input builder because the write schema contains nested records. A saved draft is not automatically deliverable. Advertisers can submit a ready draft for review and pause or resume an eligible campaign; approval and launch are administrator actions. Editing creates a new draft revision while prior clicks keep the earlier terms.
Campaign write fields
POST /campaigns and POST /campaigns/{campaignId}/revisions accept the same full CampaignWriteInput. The revision endpoint does not behave like a partial PATCH. Use expectedVersion on a revision to detect another editor's change; a mismatch produces campaign_version_conflict.
| Group | Fields and rules |
|---|---|
| Owner and identity | advertiserId selects an owned advertiser profile. name is at least three characters. Direct advertisers cannot set managed source or partner-wall modes. |
| Objective and format | objective: SIGNUP, PURCHASE, INSTALL, ENGAGEMENT, or CUSTOM. offerType: SINGLE_ACTION or MULTI_REWARD for self-service. pricingModel: CPI, CPA, or CPE. taskType and categories classify suitability. |
| Advertised property | platforms contains exactly one of web, android, ios. advertisedAssetId is a current validated owned asset; assetUrl and assetIdentifier describe it. |
| Public copy | Required description, requirements, disclaimer, userInstructions; optional title, headline, ctaText, thingsToKnow, and paymentRequired. |
| Media and links | Required HTTPS landingUrlTemplate with {click_id} for S2S. Optional HTTPS previewUrl, supportUrlTemplate, iconUrl, heroImageUrl, teaserVideoUrl, and up to six gallery URLs. creativeAssetIds must belong to the asset and advertiser. |
| Attribution | trackingPartner defaults to CUSTOM_S2S; trackingLinkTemplate, callbackIpAllowlist, attributionWindowMinutes, sessionHours, and provider configuration depend on the selected provider. |
| Finance | budget, optional bid, each goal's grossRevenue and publisherPayout are display money amounts converted to integer micros on the server. Publisher payout cannot exceed gross revenue. |
| Audience | countries (two-letter codes), optional US stateCodes, placements (offerwall, app-inbox, web-landing), trafficSources (android, ios, desktop), deviceTypes, manufacturer include/exclude, OS/browser versions, and optional UTC dayParting. |
| Limits and time | dailyCap, monthlyCap, nextMonthCap, userCap, startAt, endAt, priority and featured status. End must follow start; browser versions apply only to web and OS versions only to mobile. |
| Goals | At least one goals item. Each has name, stable unique externalGoalId, grossRevenue, publisherPayout, optional description, pending/completion minutes, repeatability, prerequisite earlier goal IDs, and availability window. |
{
"advertiserId": "ADVERTISER_ID",
"name": "Verified signup offer",
"objective": "SIGNUP",
"platforms": ["web"],
"advertisedAssetId": "VALIDATED_ASSET_ID",
"description": "Create and verify a new account.",
"requirements": "New users only; verify the email address.",
"disclaimer": "Rewards are confirmed after server verification.",
"userInstructions": "Open the site, register, and verify your email.",
"landingUrlTemplate": "https://advertiser.example/join?rr_click_id={click_id}",
"trackingPartner": "CUSTOM_S2S",
"creativeAssetIds": ["crv_VALIDATED_CREATIVE_ID"],
"countries": ["US"],
"budget": 100,
"goals": [{"name":"Verified signup","externalGoalId":"signup_verified","grossRevenue":2,"publisherPayout":1.5}]
}
The sample shows structure, not a ready campaign: the asset and creative IDs must be real validated records owned by that advertiser, the tracking credential must exist, and the environment must enable the provider and delivery. A 201 response contains the full campaign with campaignId, status: "DRAFT", mapped display budget/spent fields, active revision, and revision history. Keep IDs opaque and avoid assuming currency minor units equal internal micros.
Readiness and status transitions
GET /campaigns/{campaignId}/readiness returns campaignId, boolean ready, errors, and optimisticVersion. Typical errors include validated_asset_required, validated_creative_required, positive_budget_required, goal_required, country_target_required, certified_tracking_provider_required, and custom_s2s_credential_required. Fix each error before requesting review.
{"campaignId":"CAMPAIGN_ID","ready":false,"errors":["validated_creative_required"],"optimisticVersion":1}
| Current status | Advertiser action | Subsequent action |
|---|---|---|
DRAFT | Submit ready campaign as IN_REVIEW; archive only by an administrator. | Administrator may return to draft or approve. |
IN_REVIEW | Wait for review or inspect notes; administrator controls approval. | Approved campaign can be launched by administrator. |
APPROVED | Check funding and intended start time. | Administrator moves to LIVE and reserves budget. |
LIVE | Pause to PAUSED if broken or incorrect. | A new revision returns to draft review. |
PAUSED | Resume to LIVE only when previously approved and still eligible. | End/archive otherwise require administrator. |
ENDED / ARCHIVED | Read history and reports. | A new campaign or clone is needed. |
The transition body is {"status":"IN_REVIEW","reviewNotes":"Optional note"}. Invalid status changes return a transition error. Budget reserve can fail even after approval if available balance is insufficient. GET /campaigns/{campaignId}/audit returns {items} of status, revision, and operator activity. A clone creates a new draft; review every goal, URL, creative, and budget before using it.
Tracking configuration
| Method | Path | Purpose |
|---|---|---|
| GET | /campaigns/{campaignId}/tracking | Current callback endpoint and setup. |
| POST | /campaigns/{campaignId}/tracking/custom-s2s/credentials | Create or retrieve metadata. A newly generated secret appears only in the 201 response. |
| POST | /campaigns/{campaignId}/tracking/custom-s2s/test | Verify the stored key in memory, without external delivery or accounting. |
| POST | /campaigns/{campaignId}/tracking/custom-s2s/rotate | Stage a new key; JSON body has activateAfter as a date/time. |
Stage rotation five minutes to seven days ahead; the old key overlaps for 24 hours after activation. Update the sender before activation. Managed MMP credential endpoints are available for the campaigns that use them.
Reporting and billing reads
GET /campaigns/{campaignId}/report returns delivery and reconciliation data when offer delivery is enabled; ?format=csv returns a CSV download. See the report schema. Shared account balance, allocations, funding, and invoices are in the billing reference. Admin operations are outside this advertiser reference.
All campaign IDs are opaque. Readiness, role checks, feature gates, and status can reject a syntactically valid request. See create an offer, operate it, and errors.