Campaign management

Use the Advertiser API to list, inspect, update, and change the status of campaigns owned by the authenticated Nexus member.

Item	Value
Base URL	`https://example.com/api/v1`
Authentication	Nexus member access JWT or the secure member session
Ownership	The backend derives the advertiser UID from the authenticated member
Update model	Read the complete campaign, modify it, and send the complete object back

Member authentication is different

These routes do not accept a Search/XML publisher API key. Use the member access token returned by the Nexus tenant backend:

http

Authorization: Bearer MEMBER_ACCESS_TOKEN

Endpoints at a glance

Method	Endpoint	Purpose
`GET`	`/login/campaigns/campaigns`	List campaigns owned by the member
`GET`	`/login/campaigns/{cid}`	Load the complete editable campaign and tenant validation settings
`PUT`	`/login/campaigns/{cid}`	Validate and update one owned campaign
`PUT`	`/login/campaigns/update-status`	Change the status of one or more owned campaigns

The examples below assume:

bash

export NEXUS_BACKEND="https://example.com/api/v1"
export MEMBER_ACCESS_TOKEN="YOUR_MEMBER_ACCESS_TOKEN"

List campaigns

http

GET /login/campaigns/campaigns

Query parameters

Parameter	Required	Description
`page`	No	Page number, starting from `1`. Default: `1`.
`perPage`	No	Rows per page from `1` to `200`. Default: `20`.
`sort`	No	Field used by the Nexus campaign table, for example `cid` or `name`.
`order`	No	`asc` or `desc`. Default: `desc`.
`query`	No	Text searches campaign names; a numeric value matches an exact CID.
`status`	No	Campaign status code from `0` to `4`.
`types`	No	Repeat the parameter to include multiple enabled Nexus campaign types.

Request example

bash

curl --get "$NEXUS_BACKEND/login/campaigns/campaigns" \
  --header "Authorization: Bearer $MEMBER_ACCESS_TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "perPage=20" \
  --data-urlencode "query=summer" \
  --data-urlencode "status=1" \
  --data-urlencode "types=48" \
  --data-urlencode "types=64"

Response example

json

{
  "status": "success",
  "message": "Feeds data retrieved successfully",
  "data": {
    "data": [
      {
        "cid": 123,
        "uid": 451,
        "type_name": "Push Ads (CPC)",
        "name": "Summer Push US",
        "website": "",
        "geo": ["US"],
        "payout": 0.03,
        "d_revenue": 200,
        "t_revenue": 2000,
        "daily_budget": 75.42,
        "total_budget": 910.18,
        "bid_control_count": 2,
        "status": 1,
        "status_name": "Active"
      }
    ],
    "total": 1,
    "currentPage": 1,
    "totalPages": 1
  }
}

Only the member's campaigns are returned. Supplying a UID for another advertiser does not expand access.

Get campaign edit data

http

GET /login/campaigns/{cid}

Always call this endpoint immediately before editing. It returns three objects:

campaign — the complete current campaign payload;
campaign_types — enabled types with the tenant's pricing and bid limits;
settings — tenant features and validation settings such as minimum budget and bid-control availability.

Request example

bash

curl "$NEXUS_BACKEND/login/campaigns/123" \
  --header "Authorization: Bearer $MEMBER_ACCESS_TOKEN"

Response example

json

{
  "status": "success",
  "message": "Found campaign",
  "data": {
    "campaign": {
      "cid": 123,
      "uid": 451,
      "name": "Summer Push US",
      "type": 48,
      "status": 1,
      "payout": 0.03,
      "clickurl": "https://advertiser.example/landing?click_id=[clickid]",
      "title": "Your daily offer",
      "description": "Open the offer and see today's available promotion.",
      "icon": { "url": "https://cdn.example.com/push/icon.png" },
      "image": { "url": "https://cdn.example.com/push/image.jpg" },
      "enable_budget": 1,
      "d_revenue": 200,
      "t_revenue": 2000,
      "geo_enabled": 0,
      "geo": ["US"],
      "os_enabled": 1,
      "os": [],
      "devices_enabled": 1,
      "devices": [],
      "bidControl": []
    },
    "campaign_types": {
      "48": {
        "name": "Push Ads",
        "pricing": "CPC",
        "minBid": 0.01,
        "maxBid": 5
      }
    },
    "settings": {
      "enable_bidcontrol": true,
      "enable_freq_cap": true,
      "enable_traffic_speed": true,
      "edit_clickurl": true,
      "min_budget": 10,
      "postbackurl": "https://example.com/postback"
    }
  }
}

Treat returned settings as authoritative

Campaign types, bid limits, minimum budgets, and enabled features can differ between Nexus tenants. Do not hard-code the example values.

Update a campaign

http

PUT /login/campaigns/{cid}

The member UI and API use a read-modify-write flow. The backend validates the complete payload against the selected campaign type and tenant settings.

Step 1: read the latest version

bash

curl "$NEXUS_BACKEND/login/campaigns/123" \
  --header "Authorization: Bearer $MEMBER_ACCESS_TOKEN"

Take the data.campaign object from this response.

Step 2: change only the intended values

For example, change the bid and daily budget while preserving the remaining fields:

json

{
  "cid": 123,
  "uid": 451,
  "name": "Summer Push US",
  "type": 48,
  "status": 1,
  "payout": 0.04,
  "clickurl": "https://advertiser.example/landing?click_id=[clickid]",
  "title": "Your daily offer",
  "description": "Open the offer and see today's available promotion.",
  "icon": { "url": "https://cdn.example.com/push/icon.png" },
  "image": { "url": "https://cdn.example.com/push/image.jpg" },
  "enable_budget": 1,
  "d_revenue": 250,
  "t_revenue": 2000,
  "enable_time": 0,
  "enable_shedule": 0,
  "shedule": [],
  "freq_cap": 0,
  "freq_counter": 1,
  "traffic_speed": 0,
  "traffic_speed_counter": 0,
  "geo_enabled": 0,
  "geo": ["US"],
  "os_enabled": 1,
  "os": [],
  "os_versions_enabled": 1,
  "os_versions": [],
  "browsers_enabled": 1,
  "browsers": [],
  "browser_versions_enabled": 1,
  "browser_versions": [],
  "devices_enabled": 1,
  "devices": [],
  "keywords_enabled": 1,
  "keywords_whitelist": "",
  "keywords_blocklist": "",
  "bidControl": []
}

Step 3: submit the complete object

bash

curl --request PUT "$NEXUS_BACKEND/login/campaigns/123" \
  --header "Authorization: Bearer $MEMBER_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data @campaign-123.json

Successful response:

json

{
  "status": "success",
  "message": "Campaign updated successfully"
}

Step 4: re-read and verify

Call GET /login/campaigns/123 again and confirm the persisted bid, budget, targeting, and status.

Complete update payload required

Do not build an update from a cached list row or a hand-written subset. A list row is not an editable campaign. Omitting conditional settings can reset values or fail validation.

Campaign field groups

Identity and pricing

Field	Requirement	Description
`cid`	Returned by GET	Campaign ID. The path CID remains authoritative during an update.
`uid`	Required	Advertiser owner. Member requests cannot use it to update another account.
`name`	Required	Campaign name, maximum 255 characters.
`type`	Required	An enabled key from `campaign_types`.
`status`	Required	Status code `0` through `4`.
`payout`	Required	Bid within the selected type's returned `minBid` and `maxBid`.
`clickurl`	CPC/CPV	HTTP(S) destination; Nexus URL macros are allowed.
`website`	CPM	Advertiser's primary ad domain as a valid HTTP(S) URL.

Creative fields

Field	Applies to	Rule
`title`	Contextual and Push	Required, maximum 25 characters.
`description`	Contextual and Push	Required, maximum 75 characters.
`icon`	Push	Required image object returned by Nexus.
`image`	Push	Required main image object returned by Nexus.

Budget, dates, and delivery

Field	Description
`enable_budget`	Enables daily and total campaign budgets.
`d_revenue`	Daily budget; must satisfy `settings.min_budget` when budgeting is enabled.
`t_revenue`	Total budget; `0` means unlimited, otherwise it must satisfy the tenant minimum.
`enable_time`	Enables the start/end date window.
`create`, `create_time`	Start date and time. Required when the time window is enabled.
`expire`, `expire_time`	End date and time. The end cannot precede the start.
`enable_shedule`	Enables the weekly delivery schedule. The spelling is part of the existing API.
`shedule`	Weekly schedule returned by Nexus; preserve all 168 hourly values.
`shedule_timezone`	Required when the weekly schedule is enabled.
`freq_cap`, `freq_counter`	Frequency-cap mode and positive counter when required by the type/settings.
`traffic_speed`, `traffic_speed_counter`	Traffic pacing; when enabled, the counter must be a whole number of at least `1000`.

Targeting selectors

The current API uses a selector flag together with an array:

a selector flag of 1 means all available values and the backend normalizes the array to [];
a selector flag of 0 means custom targeting and requires at least one selected array value.

Flag	Values	Dimension
`geo_enabled`	`geo`	Countries
`os_enabled`	`os`	Operating systems
`os_versions_enabled`	`os_versions`	OS versions
`browsers_enabled`	`browsers`	Browsers
`browser_versions_enabled`	`browser_versions`	Browser versions
`devices_enabled`	`devices`	Device types
`categories_enabled`	`categories`	CPM categories
`lang_enabled`	`lang`	CPM languages
`connection_enabled`	`connection`	CPM connection types, except Popunder types
`traffic_type_enabled`	`traffic_type`	CPM traffic types, except Popunder types
`exchanges_enabled`	`exchanges`	CPM exchanges; values are positive numeric IDs

Traffic filters such as IP, domain, publisher, site/app, SSP, bundle ID, carrier, and keyword allow/block lists must be copied from the latest GET response unless you intentionally change them.

Bid controls

bidControl is available only when settings.enable_bidcontrol is true and the pricing model is CPC or CPV. Preserve the complete array and its backend-provided objects when editing unrelated fields.

Update campaign status

http

PUT /login/campaigns/update-status

Pause one campaign

bash

curl --request PUT "$NEXUS_BACKEND/login/campaigns/update-status" \
  --header "Authorization: Bearer $MEMBER_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"ids":[123],"status":3}'

Activate several campaigns

json

{
  "ids": [123, 124, 125],
  "status": 1
}

Status	Meaning	Member behavior
`0`	Pending	Members cannot approve or reject pending campaigns.
`1`	Active	Requires at least `$1.00` available advertiser balance.
`2`	Suspended	Used by the member UI as removal/suspension.
`3`	Paused	Stops delivery without suspending the campaign.
`4`	Scheduled	Campaign follows its configured start/schedule settings.

Errors and safe recovery

Status	Typical cause	What to do
`400`	Invalid operation or backend business rule.	Read `message`, reload the campaign, and correct the request.
`401`	Missing or expired member authentication.	Obtain a new member access token.
`402`	Insufficient balance while activating.	Fund the advertiser account before retrying.
`403`	Foreign campaign, wrong role, or forbidden operation.	Confirm member ownership and permissions.
`404`	CID missing or not owned by this member.	Do not retry an unverified CID.
`422`	Field-level campaign validation failed.	Use the returned validation details and the current tenant settings.

Never retry a failed PUT with fewer fields. Reload the campaign, apply the intended changes again, and submit a newly validated complete payload.

Interactive API reference

Use the Advertiser OpenAPI reference to inspect schemas and responses. The workflow and conditional rules on this page remain the authoritative integration guide.

Campaign management ​

Endpoints at a glance ​

List campaigns ​

Query parameters ​

Request example ​

Response example ​

Get campaign edit data ​

Request example ​

Response example ​

Update a campaign ​

Step 1: read the latest version ​

Step 2: change only the intended values ​

Step 3: submit the complete object ​

Step 4: re-read and verify ​

Campaign field groups ​

Identity and pricing ​

Creative fields ​

Budget, dates, and delivery ​

Targeting selectors ​

Bid controls ​

Update campaign status ​

Pause one campaign ​

Activate several campaigns ​

Errors and safe recovery ​

Interactive API reference ​

Campaign management

Endpoints at a glance

List campaigns

Query parameters

Request example

Response example

Get campaign edit data

Request example

Response example

Update a campaign

Step 1: read the latest version

Step 2: change only the intended values

Step 3: submit the complete object

Step 4: re-read and verify

Campaign field groups

Identity and pricing

Creative fields

Budget, dates, and delivery

Targeting selectors

Bid controls

Update campaign status

Pause one campaign

Activate several campaigns

Errors and safe recovery

Interactive API reference