Campaign¶

A campaign is the top-level container inside an advertiser account. It carries the marketing objective and the daily budget. Nova Play runs between 2 and 4 campaigns per game; each campaign targets one geographic group (T1, SEA, LATAM or EA) and one objective (install volume or purchase value).

Campaign naming convention¶

Campaign names are machine-readable and follow this pattern:

{GAME}_{PLATFORM}_{OS}_{GEO}_{OBJECTIVE}_{YYYYMM}

Segment	Values	Meaning
`GAME`	`DMS`, `IME`, `ZSD`, `PBM`, `CML`, `CPM`, `SST`, `HTD`, `WGS`, `PSV`	Three-letter game code (Dragon Merge Saga, Idle Mining Empire, Zombie Siege Defense, Puzzle Blast Mania, Castle Match Legends, Car Park Master 3D, Sushi Shop Tycoon, Hero Tower Defense, Word Garden Story, Pixel Survivors)
`PLATFORM`	`TT`	Ad network: TikTok
`OS`	`AND`, `IOS`	Operating system of the promoted app
`GEO`	`T1`, `SEA`, `LATAM`, `EA`	Geographic group: T1 = US, GB, CA, AU, DE; SEA = VN, ID, PH, TH; LATAM = BR, MX; EA = JP, KR, TW
`OBJECTIVE`	`INSTALL`, `VALUE`	`INSTALL` optimizes for app installs, `VALUE` optimizes for purchase value (in-app events)
`YYYYMM`	e.g. `202609`	Month in which the campaign started

Example: DMS_TT_AND_T1_INSTALL_202609 is a Dragon Merge Saga Android install campaign targeting Tier-1 countries, started in September 2026. A _B suffix is appended when two campaigns would otherwise share a name.

The name is the only place where the INSTALL/VALUE objective is visible at campaign level (the objective field is APP_INSTALL for both). The ad group's optimization_goal also exposes it.

Get campaigns¶

GET /open_api/v1.3/campaign/get/

Parameters¶

Name	Type	Required	Description
`advertiser_id`	string	Yes	Advertiser account id.
`filtering`	JSON object	No	Filter conditions, see below.
`fields`	JSON array of strings	No	Response fields to return. Defaults to all fields. Unknown names fail with `40001`.
`page`	integer	No	Page number, starting at `1`. Default `1`.
`page_size`	integer	No	Rows per page, `1`–`1000`. Default `10`.

Filtering¶

filtering is a JSON object ({...}), not a list. Supported keys:

Key	Type	Description
`campaign_ids`	array of strings	Return only these campaign ids.
`campaign_name`	string	Exact name match.
`objective_type`	string	`APP_PROMOTION` (the only value in these accounts).
`secondary_status`	string	One of the status values listed below.

Example: filtering={"campaign_ids":["1871286220402645533"]}. Unsupported keys fail with 40001 and the message lists the supported keys.

Request¶

curl -s -G "https://business-api.huydata.com/open_api/v1.3/campaign/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode "advertiser_id=7643153585721644371" \
  --data-urlencode "page_size=100"

Response¶

{
  "code": 0,
  "message": "OK",
  "request_id": "b3f6b70ae6344d3d923b",
  "data": {
    "list": [
      {
        "campaign_id": "1871286220402645533",
        "campaign_name": "DMS_TT_AND_EA_INSTALL_202602",
        "advertiser_id": "7643153585721644371",
        "objective_type": "APP_PROMOTION",
        "app_promotion_type": "APP_INSTALL",
        "campaign_type": "REGULAR_CAMPAIGN",
        "budget_mode": "BUDGET_MODE_DAY",
        "budget": 390.0,
        "operation_status": "ENABLE",
        "secondary_status": "CAMPAIGN_STATUS_ENABLE",
        "is_smart_performance_campaign": false,
        "objective": "APP_INSTALL",
        "create_time": "2026-02-26 03:00:00",
        "modify_time": "2026-02-26 03:00:00"
      },
      {
        "campaign_id": "1862348092944652029",
        "campaign_name": "DMS_TT_AND_SEA_INSTALL_202604",
        "advertiser_id": "7643153585721644371",
        "objective_type": "APP_PROMOTION",
        "app_promotion_type": "APP_INSTALL",
        "campaign_type": "REGULAR_CAMPAIGN",
        "budget_mode": "BUDGET_MODE_DAY",
        "budget": 190.0,
        "operation_status": "ENABLE",
        "secondary_status": "CAMPAIGN_STATUS_ENABLE",
        "is_smart_performance_campaign": false,
        "objective": "APP_INSTALL",
        "create_time": "2026-04-21 07:00:00",
        "modify_time": "2026-04-21 07:00:00"
      },
      ...
    ],
    "page_info": {"page": 1, "page_size": 100, "total_number": 3, "total_page": 1}
  }
}

Field	Type	Description
`campaign_id`	string	Numeric campaign id (19 digits, starts with `18`).
`campaign_name`	string	See naming convention above.
`advertiser_id`	string	Owning account.
`objective_type`	string	Always `APP_PROMOTION`.
`app_promotion_type`	string	Always `APP_INSTALL`.
`campaign_type`	string	Always `REGULAR_CAMPAIGN`.
`budget_mode`	string	`BUDGET_MODE_DAY`: `budget` is a daily budget.
`budget`	number	Daily budget in the account currency (USD). The only non-string numeric field.
`operation_status`	string	`ENABLE` or `DISABLE` (advertiser switched the campaign off).
`secondary_status`	string	Delivery status, see table below.
`is_smart_performance_campaign`	boolean	Always `false`.
`objective`	string	Always `APP_INSTALL`, including for `VALUE` campaigns.
`create_time`	string	`YYYY-MM-DD HH:MM:SS` in UTC.
`modify_time`	string	`YYYY-MM-DD HH:MM:SS` in UTC.

Status values¶

`operation_status`	`secondary_status`	Meaning
`ENABLE`	`CAMPAIGN_STATUS_ENABLE`	Delivering.
`DISABLE`	`CAMPAIGN_STATUS_DISABLE`	Paused by the advertiser. Campaigns are occasionally paused for 3–10 days and then resumed.
`ENABLE`	`CAMPAIGN_STATUS_TIME_DONE`	The scheduled end date has passed. The campaign no longer delivers but it still appears in this list and its historical rows are still returned by Reporting.

Statuses reflect the state today. A campaign that is CAMPAIGN_STATUS_TIME_DONE now may have delivered during the dates you are pulling; do not use today's status to filter historical reports.

Filtered request with selected fields¶

curl -s -G "https://business-api.huydata.com/open_api/v1.3/campaign/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode "advertiser_id=7643153585721644371" \
  --data-urlencode 'filtering={"campaign_ids":["1871286220402645533"]}' \
  --data-urlencode 'fields=["campaign_id","campaign_name","operation_status","budget"]'

{
  "code": 0,
  "message": "OK",
  "request_id": "04d1da08ff564297bf2e",
  "data": {
    "list": [
      {"campaign_id": "1871286220402645533", "campaign_name": "DMS_TT_AND_EA_INSTALL_202602", "operation_status": "ENABLE", "budget": 390.0}
    ],
    "page_info": {"page": 1, "page_size": 10, "total_number": 1, "total_page": 1}
  }
}

Errors¶

Missing advertiser_id → 40001 Parameter 'advertiser_id' is required.
filtering sent as a list (the Reporting format) → 40001 Parameter 'filtering' must be a JSON-encoded dict.
filtering={"campaign_id": ...} (singular) → 40001 Unsupported filtering key 'campaign_id'. Supported: campaign_ids, campaign_name, objective_type, secondary_status
fields=["campaign_id","status"] → 40001 Field 'status' is not supported for campaign.